• Stars
    star
    109
  • Rank 319,077 (Top 7 %)
  • Language
    JavaScript
  • License
    GNU General Publi...
  • Created over 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

AdGuard scriptlets library

AdGuard Scriptlets and Redirect Resources

AdGuard's Scriptlets and Redirect resources library which provides extended capabilities for content blocking.


Scriptlets

Scriptlet is a JavaScript function which can be used in a declarative manner in AdGuard filtering rules.

AdGuard supports a lot of different scriptlets. Please note, that in order to achieve cross-blocker compatibility, we also support syntax of uBO and ABP.

Syntax

rule = [domains]  "#%#//scriptlet(" scriptletName arguments ")"
  • scriptletName (mandatory) is a name of the scriptlet from AdGuard's scriptlets library
  • arguments (optional) a list of String arguments (no other types of arguments are supported)

Remarks

  • The meaning of the arguments depends on the scriptlet.

  • Special characters in scriptlet argument must be escaped properly:

    • valid:
      • 'prop["nested"]'
      • "prop['nested']"
      • 'prop[\'nested\']'
      • "prop[\"nested\"]"
    • not valid:
      • 'prop['nested']'
      • "prop["nested"]"
  • You can use either single or double quotes for the scriptlet name and arguments. Single quote is recommended but not for cases when its usage makes readability worse, e.g. ".css('display','block');" is more preferred then '.css(\'display\',\'block\');'.

Example

example.org#%#//scriptlet('abort-on-property-read', 'alert')
example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')

This rule applies the abort-on-property-read scriptlet on all pages of example.org and its subdomains, and passes one argument to it (alert).

Trusted scriptlets

Trusted scriptlets are scriptlets with extended functionality. Their names are prefixed with trusted-, e.g trusted-click-element, to be easily distinguished from common scriptlets.

Restriction

Trusted scriptlets application must be restricted due to dangerous nature of their capabilities. Allowed sources of trusted scriptlets are:

  • filters created by AdGuard Team,
  • custom filters which were installed as trusted,
  • user rules.

Trusted scriptlets has no compatibility table as they are not compatible with any other blocker.

Trusted scriptlets list

Redirect resources

AdGuard is able to redirect web requests to a local "resource".

Syntax

AdGuard uses the same filtering rule syntax as uBlock Origin. Also, it is compatible with ABP $rewrite=abp-resource modifier.

$redirect is a modifier for the basic filtering rules so rules with this modifier support all other basic modifiers like $domain, $third-party, $script, etc.

The value of the $redirect modifier must be the name of the resource that will be used for redirection. See the list of available redirect resources.

Priority of $redirect rules is described in the Knowledge Base.

Examples

  • ||example.org/script.js$script,redirect=noopjs β€” redirects all requests to script.js to the resource named noopjs.
  • ||example.org/test.mp4$media,redirect=noopmp4-1s β€” requests to example.org/test.mp4 will be redirected to the resource named noopmp4-1s.

uBlock Origin specifies additional resource name none that can disable other redirect rules. AdGuard does not support it, use $badfilter to disable specific rules.


Development

How to build

Install dependencies:

yarn install

Build for CoreLibs:

yarn corelibs

Build dev (rebuild js files on every change):

yarn watch

Build for Extension

In scriptlets directory install dependencies, build scriptlets bundle, and create scriptlets link.

yarn
yarn build
yarn link

In tsurlfilter directory install and link dependencies, link scriptlets, move into package and build, and create tsurlfilter link.

lerna bootstrap

yarn link "@adguard/scriptlets"

cd ./packages/tsurlfilter
yarn build
yarn link

In extension directory install dependencies, link packages and build

yarn

yarn link @adguard/scriptlets
yarn link @adguard/tsurlfilter

yarn dev

How to test

Some tests are run in QUnit, some in Jest.

Run all tests:

yarn test
  1. QUnit is used for testing of scriptlets, redirects, and helpers:

    yarn test:qunit [scriptlets | redirects | helpers]
    

    For scriptlets and redirects test run can be more specific:

    // node test run
    yarn test:qunit scriptlets --name set-cookie
    yarn test:qunit redirects --name ati-smarttag
    
    // gui test run
    yarn test:qunit scriptlets --name set-cookie --gui
    yarn test:qunit redirects --name ati-smarttag --gui

    For debugging purposes after some test is running in gui mode, you may change your scriptlet/redirect code, and without stopping the server run in new terminal:

    yarn test:qunit scriptlets --name set-cookie --build
  2. Run all jest tests:

    yarn test:jest

    or limit the testing β€” testRegex may be specified in jest.config.js or specify test name in command line, e.g.:

    yarn test:jest -t isValidScriptletRule

To run browserstack tests create .env file or copy and rename .env-example.

Fill in <username> and <key> with data from your Browserstack profile. Run next command:

yarn browserstack

Tests run by jest should be named .spec.js, so they will be not included in the QUnit tests.

Debugging

Use debugger; statement where you need it, run

yarn test

and open needed HTML file from tests/dist in your browser with devtools

How to update wiki

There are two scripts to update wiki:

  1. yarn wiki:build-table β€” checks compatibility data updates and updates the compatibility table. Should be run manually while the release preparation.
  2. yarn wiki:build-docs β€” updates wiki pages about-scriptlets.md and about-redirects.md. They are being generated from JSDoc-type comments of corresponding scriptlets and redirects source files due to @scriptlet/@redirect and @description tags. Runs automatically while the release build.

Usage

CoreLibs

For CoreLibs usage you should use dist/scriptlets.corelibs.json and dist/redirects.json.

File example:

{
    "version": "1.0.0",
    "scriptlets": [
        {
            "names": [
                "abort-on-property-read",
                "ubo-abort-on-property-read.js",
                "abp-abort-on-property-read"
            ],
            "scriptlet": "function() { ...code... }"
        },
    ]
}

Schema:

{
    "type": "object",
    "properties": {
        "version": {
            "type": "string"
        },
        "scriptlets": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "names": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "scriptlet": {
                        "type": "string"
                    }
                },
            }
        }
    }
}

NPM module

Installation

yarn add @adguard/scriptlets
npm install @adguard/scriptlets

API description

Scriptlets library

Scriptlets API methods

You are welcome to use scriptlets and redirect resources as a CJS module. They can be imported from dist/cjs/scriptlets.cjs.js:

const scriptlets = require('scriptlets');
const { redirects } = require('scriptlets');

And also there is a module at dist/scriptlets.js which has been exported to a global variable scriptlets with such methods:

invoke()
/**
 * Returns scriptlet code by `source`.
 *
 * @param {Source} source Scriptlet properties.
 *
 * @returns {string|null} Scriptlet code.
 * @throws An error on unknown scriptlet name.
 */
scriptlets.invoke(source);

where:

/**
 * @typedef {Object} Source β€” Scriptlet properties.
 * @property {string} name β€” Scriptlet name.
 * @property {Array<string>} args β€” Arguments for scriptlet function.
 * @property {'extension'|'corelibs'} engine β€” Defines the final form of scriptlet string presentation.
 * @property {string} [version] β€” Extension version.
 * @property {boolean} [verbose] β€” Flag to enable debug information printing to console.
 * @property {string} [ruleText] β€” Source rule text, needed for debug purposes.
 * @property {string} [domainName] β€” Domain name where scriptlet is applied, needed for debug purposes.
 */
getScriptletFunction()
/**
 * Returns scriptlet function by `name`.
 *
 * @param {string} name Scriptlet name
 *
 * @returns {Function} β€” Scriptlet function.
 */
scriptlets.getScriptletFunction(name);
isValidScriptletName()
/**
 * Checks whether the `name` is valid scriptlet name.
 * Uses cache for better performance.
 *
 * @param {string} name β€” Scriptlet name
 * @returns {boolean} β€” True if scriptlet name is valid.
 */
scriptlets.isValidScriptletName(name);
isValidScriptletRule()
/**
 * 1. For ADG scriptlet checks whether the scriptlet syntax and name are valid.
 * 2. For UBO and ABP scriptlet first checks their compatibility with ADG
 * by converting them into ADG syntax, and after that checks the name.
 *
 * ADG or UBO rules are "single-scriptlet", but ABP rule may contain more than one snippet
 * so if at least one of them is not valid β€” whole `ruleText` rule is not valid too.
 *
 * @param {string} ruleText β€” Any scriptlet rule β€” ADG or UBO or ABP.
 *
 * @returns {boolean} β€” True if scriptlet name is valid in rule.
 */
scriptlets.isValidScriptletRule(input);
isAdgScriptletRule(), isUboScriptletRule(), isAbpSnippetRule()
/**
 * Checks if the `rule` is AdGuard / Ubo / Abp scriptlet rule
 * @param {string} rule β€” any rule
 * @returns {boolean}
 */
scriptlets.isAdgScriptletRule(rule);
scriptlets.isUboScriptletRule(rule);
scriptlets.isAbpSnippetRule(rule);
convertUboToAdg()
/**
 * Converts Ubo scriptlet rule to AdGuard
 * @param {string} rule β€” Ubo rule
 * @returns {string[]} β€” array with single AdGuard scriptlet rule
 */
scriptlets.convertUboToAdg(rule);

Note that parameters in UBO rule should be separated by comma + space. Otherwise, the rule is not valid.

convertAbpToAdg()
/**
 * Converts Abp snippet rule to AdGuard
 * @param {string} rule β€” Abp rule
 * @returns {string[]} β€” array with AdGuard scriptlet rule or rules if Abp-rule has few snippets in one line
 */
scriptlets.convertAbpToAdg(rule);
convertScriptletToAdg()
/**
 * Converts any scriptlet rule into AdGuard syntax rule.
 * Comment is returned as is.
 *
 * @param {string} rule β€” Scriptlet rule.
 *
 * @returns {string[]} β€” Array of AdGuard scriptlet rules: one array item for ADG and UBO or few items for ABP.
 * For the ADG `rule`, validates its syntax and returns an empty array if it is invalid.
 */
scriptlets.convertScriptletToAdg(rule);
convertAdgToUbo()
/**
 * Converts AdGuard scriptlet rule to UBO one
 * @param {string} rule β€” AdGuard scriptlet rule
 * @returns {string} β€” UBO scriptlet rule
 */
scriptlets.convertAdgToUbo(rule);

Redirects API methods

import { redirects } from '@adguard/scriptlets';
getCode()
/**
 * Returns redirects code
 * @param {Source} source
 * @returns {string}
 */
redirects.getCode(source);
isAdgRedirectRule()
/**
 * Checks whether the `rule` is AdGuard redirect resource rule.
 * Discards comments and JS rules and checks whether the `rule` has $redirect or $redirect-rule modifier
 * @param {string} rule
 */
redirects.isAdgRedirectRule(rule)
isValidAdgRedirectRule()
/**
 * Checks whether the `rule` is **valid** AdGuard redirect resource rule.
 * No matter $redirect or $redirect-rule
 * @param {string} rule
 * @returns {boolean}
 */
redirects.isValidAdgRedirectRule(rule);
isAdgRedirectCompatibleWithUbo()
/**
 * Checks whether the AdGuard redirect `rule` has Ubo analog.
 * Needed for Adg->Ubo conversion. No matter $redirect or $redirect-rule modifier is used
 * @param {string} rule β€” AdGuard rule
 * @returns {boolean} β€” true if the rule can be converted to Ubo syntax
 */
redirects.isAdgRedirectCompatibleWithUbo(rule);
isUboRedirectCompatibleWithAdg()
/**
 * Checks if the Ubo redirect `rule` has AdGuard analog.
 * Needed for Ubo->Adg conversion. No matter $redirect or $redirect-rule modifier is used
 * @param {string} rule β€” Ubo rule
 * @returns {boolean} β€” true if the rule can be converted to AdGuard syntax
 */
redirects.isUboRedirectCompatibleWithAdg(rule);
isAbpRedirectCompatibleWithAdg()
/**
 * Checks whether the Abp redirect `rule` has AdGuard analog. Needed for Abp->Adg conversion
 * @param {string} rule β€” Abp rule
 * @returns {boolean} β€” true if the rule can be converted to AdGuard syntax
 */
redirects.isAbpRedirectCompatibleWithAdg(rule);
convertUboRedirectToAdg()
/**
 * Converts Ubo redirect resource rule to AdGuard syntax.
 * No matter $redirect or $redirect-rule modifier is used
 * @param {string} rule β€” Ubo rule
 * @returns {string} β€” Adg rule
 */
redirects.convertUboRedirectToAdg(rule);
convertAbpRedirectToAdg()
/**
 * Converts Abp redirect resource rule to AdGuard syntax
 * @param {string} rule β€” Abp rule
 * @returns {string} β€” Adg rule
 */
redirects.convertAbpRedirectToAdg(rule);
convertRedirectToAdg()
/**
 * Checks whether the `rule` is any redirect rule and converts it to AdGuard syntax.
 * No matter $redirect or $redirect-rule modifier is used
 * @param {string} rule β€” any resource rule
 * @returns {string} β€” valid Adguard redirect resource rule
 */
redirects.convertRedirectToAdg(rule);
convertRedirectNameToAdg()
/**
 * Converts a redirect name to ADG compatible one, if possible
 *
 * @param {string} name Redirect name to convert
 * @returns {string|undefined} Converted ADG compatible redirect name or `undefined` if the redirect isn't supported
 */
redirects.convertRedirectNameToAdg(rule);
convertAdgRedirectToUbo()
/**
 * Converts Adg redirect rule to Ubo syntax.
 * No matter $redirect or $redirect-rule modifier is used
 * @param {string} rule β€” Adg rule
 * @returns {string} β€” Ubo rule
 */
redirects.convertAdgRedirectToUbo(rule);
getRedirectFilename()
/**
 * For a given name or alias of redirect returns the corresponding filename
 * @param {string} name β€” name or alias of redirect
 * @returns {string} β€” Redirect's filename with extension
 */
redirects.getRedirectFilename(name);
Redirects class
import { Redirects } from '@adguard/scriptlets';

/**
 * Converts rawYaml into JS object with sources titles used as keys
 */
const redirects = new Redirects(rawYaml)

where rawYaml is a string with YAML content located in dist/redirects.yml.

getRedirect()
/**
 * Returns redirect source object by title
 */
const redirect = redirects.getRedirect('noopjs');

/**
 * Redirect is an object with following props:
 * {
 *     title: 1x1-transparent.gif
 *     comment: http://probablyprogramming.com/2009/03/15/the-tiniest-gif-ever
 *     contentType: image/gif;base64
 *     content: R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==
 * }
 */
isBlocking()
/**
 * Check if redirect is blocking, e.g. click2load.html
 */
const isBlocking = redirect.isBlocking('click2load.html');

Browser Compatibility

Browser Version
Chrome βœ… 55
Firefox βœ… 52
Edge βœ… 15
Opera βœ… 42
Safari βœ… 11
Internet Explorer ❌

Projects using Scriptlets

More Repositories

1

AdGuardHome

Network-wide ads & trackers blocking DNS server
Go
18,381
star
2

AdguardBrowserExtension

AdGuard browser extension
JavaScript
2,427
star
3

AdguardFilters

AdGuard Content Blocking Filters
Adblock Filter List
2,331
star
4

dnsproxy

Simple DNS proxy with DoH, DoT, DoQ and DNSCrypt support
Go
1,791
star
5

AdguardForiOS

The most advanced ad blocker for iOS
JavaScript
1,289
star
6

AdguardForAndroid

Open bug tracker for Android version of AdGuard.
1,060
star
7

AdGuardForSafari

AdGuard for Safari app extension
JavaScript
875
star
8

AdGuardDNS

Public DNS resolver that protects you from ad trackers
Go
634
star
9

AdguardForWindows

AdGuard for Windows open bug tracker
568
star
10

AdGuardSDNSFilter

AdGuard Simplified Domain names filter
Adblock Filter List
491
star
11

ContentBlocker

Content blocking extension for Samsung Internet and Yandex Browser
Java
402
star
12

cname-trackers

This repository contains a list of popular CNAME trackers
JavaScript
334
star
13

AdGuardExtra

AdGuard Extra is designed to solve complicated cases when regular ad blocking rules aren't enough.
270
star
14

AdguardForMac

Open bug tracker for Mac version of AdGuard
269
star
15

PopupBlocker

Popup blocking userscript
TypeScript
220
star
16

gomitmproxy

Simple golang mitm proxy implementation
Go
155
star
17

FiltersRegistry

Known filters subscriptions transformed for better compatibility with AdGuard
Adblock Filter List
152
star
18

AdguardKnowledgeBase

Adguard Knowledge Base
140
star
19

AdGuardMV3

AdGuard browser extension prototype based on the new Manifest V3
TypeScript
121
star
20

HostlistsRegistry

Known hosts blocklists that are made available to the users of AdGuard products
JavaScript
113
star
21

AdguardAssistant

Adguard Assistant userscript
JavaScript
110
star
22

HostlistCompiler

A simple tool that compiles hosts blocklists from multiple sources
JavaScript
95
star
23

BlockYouTubeAdsShortcut

This repo contains the code for blocking YouTube ads that is supposed to be run by an iOS shortcut
JavaScript
85
star
24

AdGuardVPNForAndroid

AdGuard VPN Android app open bug tracker
81
star
25

DisableAMP

Disable AMP userscript
JavaScript
76
star
26

DnsLibs

DNS filtering library
C++
75
star
27

urlfilter

AdGuard content blocking library in golang
Go
71
star
28

AdGuardVPNExtension

AdGuard VPN Chrome and Firefox extension
TypeScript
57
star
29

AnonymousRedirect

Very simple HTML page that is used for anonymous redirect
HTML
55
star
30

ExtendedCss

A TypeScript library for non-standard element selecting β€” :contains(), :matches-css(), etc., and applying CSS styles with extended properties.
TypeScript
54
star
31

HttpsExclusions

Centralized repo for HTTPS exclusions
JavaScript
48
star
32

KnowledgeBaseDNS

AdGuard DNS knowledge base
JavaScript
47
star
33

StealthMode

JavaScript
46
star
34

Userscripts

Userscripts made by our team
JavaScript
42
star
35

AdGuardVPNForWindows

AdGuard VPN Windows app open bug tracker
39
star
36

VscodeAdblockSyntax

TM language plugin with ad blocking rules syntax
37
star
37

FiltersCompiler

A tool that compiles & validates filters
JavaScript
36
star
38

tsurlfilter

AdGuard content blocking library
TypeScript
35
star
39

CoreLibs

Core Adguard libraries
33
star
40

BrowserAssistant

AdGuard Browser Assistant
JavaScript
33
star
41

AGLint

Universal adblock filter list parser, linter and converter
TypeScript
28
star
42

KnowledgeBase

AdGuard knowledge base
JavaScript
26
star
43

AdGuardVPNForiOS

AdGuard VPN iOS app open bug tracker
25
star
44

SafariConverterLib

Swift library that converts AdGuard rules to Safari content blocking rules
Swift
21
star
45

AdGuardVPNForMac

AdGuard VPN Mac app open bug tracker
21
star
46

AdguardTeam.github.io

HTML
17
star
47

companiesdb

This is a companies DB that we use in AdGuard Home and AdGuard DNS.
JavaScript
16
star
48

ProxiesSetup

A simple script that sets up an HTTP and a SOCKS5 proxy (squid and danted)
Shell
16
star
49

WebBatteryTester

This application allows you to test how quick is your battery drained by web-browsing.
Java
14
star
50

golibs

Small helper Go libraries
Go
13
star
51

SafariConverter

Converter: ad blocking rules -> safari content blocker
JavaScript
12
star
52

deep-override

TypeScript
10
star
53

VerificationLibrary

Certificates verification library
C
9
star
54

go-webext

Automation for working with extension stores
Go
9
star
55

FiltersDownloader

Pre-processing library for filters subscriptions
JavaScript
9
star
56

translate

Simple internationalization library with react integration
TypeScript
8
star
57

AdGuardFiltersStats

The repo where we collect AdguardFilters statistics
JavaScript
8
star
58

ecsstree

Adblock Extended CSS supplement for CSSTree
JavaScript
7
star
59

ReportsWebApp

Allows users to report a problem with Adguard filters
JavaScript
7
star
60

NativeLibsCommon

Native libs common
C++
6
star
61

Recovery

JavaScript
5
star
62

VpnLibs

Open bug tracker for AdGuard VPN core library
5
star
63

KnowledgeBaseVPN

AdGuard VPN knowledge base
JavaScript
5
star
64

AdGuardVpnKnowledgeBase

AdGuard VPN Knowledge Base
5
star
65

LegalDocs

AdGuard's legal documents
4
star
66

SafariContentBlockerTester

Utility Safari extension for content blocker format testing.
JavaScript
4
star
67

TestCases

Used for testing puproses
JavaScript
3
star
68

SafariContentBlockerConverterCompiler

Utility scripts for building safari content blocker converter.
JavaScript
3
star
69

github-stats

Tool for calculating AdguardFilters contributors statistics
JavaScript
3
star
70

DeadDomainsLinter

Simple tool to check adblock filtering rules for dead domains.
JavaScript
2
star
71

AdGuardVPNCLI

AdGuard VPN command-line version
2
star
72

AdGuardDNSClient

Client tool for AdGuard DNS
Go
2
star
73

closure-tools-helper

TypeScript
1
star
74

dns-sde-extension

Proof-of-concept browser extension for Structured DNS errors
1
star