rules

package
v0.12.4-0...-7e3a450 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2020 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package rules contains implementation of all kinds of blocking rules

Index

Constants

View Source 
const (
	// MaskStartURL definition:
	// Matching the beginning of an address. With this character you don't
	// have to specify a particular protocol and subdomain in address mask.
	// It means, || stands for http://*., https://*., ws://*., wss://*. at once.
	MaskStartURL = "||"

	// MaskPipe definition:
	// A pointer to the beginning or the end of address. The value depends on the
	// character placement in the mask. For example, a rule swf| corresponds
	// to http://example.com/annoyingflash.swf , but not to http://example.com/swf/index.html.
	// |http://example.org corresponds to http://example.org, but not to http://domain.com?url=http://example.org.
	MaskPipe = "|"

	// MaskSeparator definition:
	// Separator character mark. Separator character is any character,
	// but a letter, a digit, or one of the following: _ - . %
	MaskSeparator = "^"

	// MaskAnyCharacter is a wildcard character. It is used to represent "any set of characters".
	// This can also be an empty string or a string of any length.
	MaskAnyCharacter = "*"

	// RegexAnyCharacter corresponds to MaskAnyCharacter.
	RegexAnyCharacter = ".*"

	// RegexSeparator corresponds to MaskSeparator.
	RegexSeparator = "([^ a-zA-Z0-9.%_-]|$)"

	// RegexStartURL corresponds to MaskStartURL.
	RegexStartURL = "^(http|https|ws|wss)://([a-z0-9-_.]+\\.)?"

	// RegexEndString corresponds to MaskPipe if it is in the end of a pattern.
	RegexEndString = "$"

	// RegexStartString corresponds to MaskPipe if it is in the beginning of a pattern.
	RegexStartString = "^"
)

Variables

View Source 
var ErrTooWideRule = errors.New("the rule is too wide, add domain, client or ctag restrictions or make it more specific")

ErrTooWideRule - returned if the rule matches all urls but has no domain, client or ctag restrictions

View Source 
var (
	// ErrUnsupportedRule signals that this might be a valid rule type,
	// but it is not yet supported by this library
	ErrUnsupportedRule = errors.New("this type of rules is unsupported")
)

Functions

func IPParser 

func IPParser(pattern string) ([]net.IPNet, error)

Parse to find ip supported patterns

Types

type CosmeticOption 

type CosmeticOption uint32

CosmeticOption is the enumeration of various content script options. Depending on the set of enabled flags the content script will contain different set of settings. 

const (
	// CosmeticOptionGenericCSS - if generic elemhide and CSS rules are enabled.
	// Can be disabled by a $generichide rule.
	CosmeticOptionGenericCSS CosmeticOption = 1 << iota
	// CosmeticOptionCSS - if elemhide and CSS rules are enabled.
	// Can be disabled by an $elemhide rule.
	CosmeticOptionCSS
	// CosmeticOptionJS - if JS rules and scriptlets are enabled.
	// Can be disabled by a $jsinject rule.
	CosmeticOptionJS

	// TODO: Add support for these flags
	// They are useful when content script is injected into an iframe
	// In this case we can check what flags were applied to the top-level frame
	CosmeticOptionSourceGenericCSS
	CosmeticOptionSourceCSS
	CosmeticOptionSourceJS

	// CosmeticOptionAll - everything is enabled
	CosmeticOptionAll = CosmeticOptionGenericCSS | CosmeticOptionCSS | CosmeticOptionJS

	// CosmeticOptionNone - everything is disabled
	CosmeticOptionNone = CosmeticOption(0)
)

CosmeticOption enumeration

type CosmeticRule 

type CosmeticRule struct {
	RuleText     string           // RuleText is the original rule text
	FilterListID int              // Filter list identifier
	Type         CosmeticRuleType // Type of the rule

	// Content meaning depends on the rule type.
	// Element hiding: content is just a selector
	// CSS: content is a selector + style definition
	// JS: text of the script to be injected
	Content string

	// Whitelist means that this rule is meant to disable rules with the same content on the specified domains
	// For instance, https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#elemhide-exceptions
	Whitelist bool

	// ExtendedCSS means that this rule is supposed to be applied by the javascript library
	// https://github.com/AdguardTeam/ExtendedCss
	ExtendedCSS bool
	// contains filtered or unexported fields
}

CosmeticRule represents a cosmetic rule (element hiding, CSS, scriptlet)

func NewCosmeticRule 

func NewCosmeticRule(ruleText string, filterListID int) (*CosmeticRule, error)

NewCosmeticRule parses the rule text and creates a

func (*CosmeticRule) GetFilterListID 

func (f *CosmeticRule) GetFilterListID() int

GetFilterListID returns ID of the filter list this rule belongs to

func (*CosmeticRule) GetPermittedDomains 

func (f *CosmeticRule) GetPermittedDomains() []string

GetPermittedDomains returns a list of permitted domains

func (*CosmeticRule) IsGeneric 

func (f *CosmeticRule) IsGeneric() bool

IsGeneric returns true if rule can be considered generic (is not limited to a specific domain)

func (*CosmeticRule) Match 

func (f *CosmeticRule) Match(hostname string) bool

Match returns true if this rule can be used on the specified hostname

func (*CosmeticRule) String 

func (f *CosmeticRule) String() string

String returns original rule text

func (*CosmeticRule) Text 

func (f *CosmeticRule) Text() string

Text returns the original rule text Implements the `Rule` interface

type CosmeticRuleType 

type CosmeticRuleType uint

CosmeticRuleType is the enumeration of different cosmetic rules 

const (
	CosmeticElementHiding CosmeticRuleType = iota // ## rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-elemhide-rules)
	CosmeticCSS                                   // #$# rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules)
	CosmeticJS                                    // #%# rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#javascript-rules)

	// TODO: Move HTML filtering rules to a different file/structure
	CosmeticHTML // $$ rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#html-filtering-rules)
)

CosmeticRuleType enumeration

type HostRule 

type HostRule struct {
	RuleText     string   // RuleText is the original rule text
	FilterListID int      // Filter list identifier
	Hostnames    []string // Hostnames is the list of hostnames that is configured
	IP           net.IP   // ip address
}

HostRule is a structure for simple host-level rules (i.e. /etc/hosts syntax). http://man7.org/linux/man-pages/man5/hosts.5.html It also supports "just domain" syntax. In this case, the IP will be set to 0.0.0.0.

func NewHostRule 

func NewHostRule(ruleText string, filterListID int) (*HostRule, error)

NewHostRule parses the rule and creates a new HostRule instance The format is: IP_address canonical_hostname [aliases...]

func (*HostRule) GetFilterListID 

func (f *HostRule) GetFilterListID() int

GetFilterListID returns ID of the filter list this rule belongs to

func (*HostRule) Match 

func (f *HostRule) Match(hostname string) bool

Match checks if this filtering rule matches the specified hostname

func (*HostRule) String 

func (f *HostRule) String() string

String returns original rule text

func (*HostRule) Text 

func (f *HostRule) Text() string

Text returns the original rule text Implements the `Rule` interface

type IPEngine 

type IPEngine struct {
	RulesCount int // RulesCount -- count of rules added to the engine

	IPRangers map[int]IPFilterRanger
	// contains filtered or unexported fields
}

IPEngine is the engine that supports quick search over ip rules

func (*IPEngine) AddRule 

func (e *IPEngine) AddRule(r *IPRule)

AddRule adds rule to the IPEngine

func (*IPEngine) Match 

func (e *IPEngine) Match(hostname string) (*IPRule, bool)

Match checks if this filtering rule matches the specified hostname

type IPFilterRanger 

type IPFilterRanger struct {
	// contains filtered or unexported fields
}

type IPRule 

type IPRule struct {
	RuleText     string      // RuleText is the original rule text
	FilterListID int         // Filter list identifier
	IPNet        []net.IPNet // ip address
}

func NewIPRule 

func NewIPRule(line string, filterListID int) (*IPRule, error)

NewIPRule created a new IP Rule from filter list line

func (*IPRule) GetFilterListID 

func (f *IPRule) GetFilterListID() int

GetFilterListID returns ID of the filter list this rule belongs to

func (*IPRule) String 

func (f *IPRule) String() string

String returns original rule text

func (*IPRule) Text 

func (f *IPRule) Text() string

Text returns the original rule text Implements the `Rule` interface

type MatchingResult 

type MatchingResult struct {
	// BasicRule - a rule matching the request.
	// It could lead to one of the following:
	// * block the request
	// * unblock the request (a regular whitelist rule or a document-level whitelist rule)
	// * modify the way cosmetic rules work for this request
	// * modify the response (see $redirect rules)
	BasicRule *NetworkRule

	// DocumentRule - a rule matching the request's referrer and having on of the following modifiers:
	// * $document -- this one basically disables everything
	// * $urlblock -- disables network-level rules (not cosmetic)
	// * $genericblock -- disables generic network-level rules
	//
	// Other document-level modifiers like $jsinject or $content will be ignored here
	// as they don't do anything
	DocumentRule *NetworkRule

	// CspRules - a set of rules modifying the response's content-security-policy
	// See $csp modifier
	CspRules []*NetworkRule

	// CookieRules - a set of rules modifying the request's and response's cookies
	// See $cookie modifier
	CookieRules []*NetworkRule

	// ReplaceRules -- a set of rules modifying the response's content
	// See $replace modifier
	ReplaceRules []*NetworkRule

	// StealthRule - this is a whitelist rule that negates stealth mode features
	// Note that the stealth rule can be be received from both rules and sourceRules
	// https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#stealth-modifier
	StealthRule *NetworkRule
}

MatchingResult contains all the rules matching a web request, and provides methods that define how a web request should be processed

func NewMatchingResult 

func NewMatchingResult(rules []*NetworkRule, sourceRules []*NetworkRule) MatchingResult

NewMatchingResult creates an instance of the MatchingResult struct and fills it with the rules. rules - a set of rules matching the request URL sourceRules - a set of rules matching the referrer nolint:gocyclo

func (*MatchingResult) GetBasicResult 

func (m *MatchingResult) GetBasicResult() *NetworkRule

GetBasicResult returns a rule that should be applied to the web request.

Possible outcomes are: * returns nil -- bypass the request. * returns a whitelist rule -- bypass the request. * returns a blocking rule -- block the request.

func (*MatchingResult) GetCosmeticOption 

func (m *MatchingResult) GetCosmeticOption() CosmeticOption

GetCosmeticOption returns a bit-flag with the list of cosmetic options

type NetworkRule 

type NetworkRule struct {
	RuleText     string // RuleText is the original rule text
	Whitelist    bool   // true if this is an exception rule
	FilterListID int    // Filter list identifier
	Shortcut     string // the longest substring of the rule pattern with no special characters

	sync.Mutex
	// contains filtered or unexported fields
}

NetworkRule is a basic filtering rule https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules

func NewNetworkRule 

func NewNetworkRule(ruleText string, filterListID int) (*NetworkRule, error)

NewNetworkRule parses the rule text and returns a filter rule

func (*NetworkRule) GetFilterListID 

func (f *NetworkRule) GetFilterListID() int

GetFilterListID returns ID of the filter list this rule belongs to

func (*NetworkRule) GetPermittedDomains 

func (f *NetworkRule) GetPermittedDomains() []string

GetPermittedDomains - returns an array of domains this rule is allowed on

func (*NetworkRule) IsGeneric 

func (f *NetworkRule) IsGeneric() bool

IsGeneric returns true if the rule is considered "generic" "generic" means that the rule is not restricted to a limited set of domains Please note that it might be forbidden on some domains, though.

func (*NetworkRule) IsHigherPriority 

func (f *NetworkRule) IsHigherPriority(r *NetworkRule) bool

IsHigherPriority checks if the rule has higher priority that the specified rule whitelist + $important > $important > whitelist > basic rules nolint: gocyclo

func (*NetworkRule) IsHostLevelNetworkRule 

func (f *NetworkRule) IsHostLevelNetworkRule() bool

IsHostLevelNetworkRule checks if this rule can be used for hosts-level blocking

func (*NetworkRule) IsOptionDisabled 

func (f *NetworkRule) IsOptionDisabled(option NetworkRuleOption) bool

IsOptionDisabled returns true if the specified option is disabled

func (*NetworkRule) IsOptionEnabled 

func (f *NetworkRule) IsOptionEnabled(option NetworkRuleOption) bool

IsOptionEnabled returns true if the specified option is enabled

func (*NetworkRule) IsRegexRule 

func (f *NetworkRule) IsRegexRule() bool

IsRegexRule returns true if rule's pattern is a regular expression

func (*NetworkRule) Match 

func (f *NetworkRule) Match(r *Request) bool

Match checks if this filtering rule matches the specified request

func (*NetworkRule) String 

func (f *NetworkRule) String() string

String returns original rule text

func (*NetworkRule) Text 

func (f *NetworkRule) Text() string

Text returns the original rule text Implements the `Rule` interface

type NetworkRuleOption 

type NetworkRuleOption uint64

NetworkRuleOption is the enumeration of various rule options In order to save memory, we store some options as a flag 

const (
	OptionThirdParty NetworkRuleOption = 1 << iota // $third-party modifier
	OptionMatchCase                                // $match-case modifier
	OptionImportant                                // $important modifier
	OptionBadfilter                                // $badfilter modifier

	OptionElemhide     // $elemhide modifier
	OptionGenerichide  // $generichide modifier
	OptionGenericblock // $genericblock modifier
	OptionJsinject     // $jsinject modifier
	OptionUrlblock     // $urlblock modifier
	OptionContent      // $content modifier
	OptionExtension    // $extension modifier

	// Whitelist -- specific to Stealth mode
	OptionStealth // $stealth

	// Content-modifying (TODO: get rid of, deprecated in favor of $redirect)
	OptionEmpty // $empty
	OptionMp4   // $mp4

	// Blocking
	OptionPopup // $popup

	// Advanced (TODO: Implement)
	OptionCsp      // $csp
	OptionReplace  // $replace
	OptionCookie   // $cookie
	OptionRedirect // $redirect

	// Blacklist-only options
	OptionBlacklistOnly = OptionPopup | OptionEmpty | OptionMp4

	// Whitelist-only options
	OptionWhitelistOnly = OptionElemhide | OptionGenericblock | OptionGenerichide |
		OptionJsinject | OptionUrlblock | OptionContent | OptionExtension |
		OptionStealth

	// Options supported by host-level network rules
	OptionHostLevelRulesOnly = OptionImportant | OptionBadfilter
)

NetworkRuleOption enumeration

func (NetworkRuleOption) Count 

func (o NetworkRuleOption) Count() int

Count returns the count of enabled options

type Request 

type Request struct {
	RequestType RequestType // request type
	ThirdParty  bool        // true if request is third-party

	// IsHostnameRequest means that the request is for a given Hostname,
	//  and not for a URL, and we don't really know what protocol it is.
	// This can be true for DNS requests, or for HTTP CONNECT, or SNI matching.
	IsHostnameRequest bool

	URL          string // Request URL
	URLLowerCase string // Request URL in lower case
	Hostname     string // Request hostname
	Domain       string // Request domain (eTLD+1)

	SourceURL      string // Source URL
	SourceHostname string // Source hostname
	SourceDomain   string // Source domain (eTLD+1)

	SortedClientTags []string // Sorted list of client tags ($ctag)
	ClientIP         string   // Client IP address
	ClientName       string   // Client name
}

Request represents a web request with all it's necessary properties

func NewRequest 

func NewRequest(url string, sourceURL string, requestType RequestType) *Request

NewRequest creates a new instance of "Request" and populates it's fields

func NewRequestForHostname 

func NewRequestForHostname(hostname string) *Request

NewRequestForHostname creates a new instance of "Request" for matching hostname. It uses "http://" as a protocol and TypeDocument as a request type.

type RequestType 

type RequestType uint32

RequestType is the request types enumeration 

const (
	// TypeDocument (main frame)
	TypeDocument RequestType = 1 << iota
	// TypeSubdocument (iframe) $subdocument
	TypeSubdocument
	// TypeScript (javascript, etc) $script
	TypeScript
	// TypeStylesheet (css) $stylesheet
	TypeStylesheet
	// TypeObject (flash, etc) $object
	TypeObject
	// TypeImage (any image) $image
	TypeImage
	// TypeXmlhttprequest (ajax/fetch) $xmlhttprequest
	TypeXmlhttprequest
	// TypeMedia (video/music) $media
	TypeMedia
	// TypeFont (any custom font) $font
	TypeFont
	// TypeWebsocket (a websocket connection) $websocket
	TypeWebsocket
	// TypeOther - any other request type
	TypeOther
)

func (RequestType) Count 

func (t RequestType) Count() int

Count returns count of the enabled flags

type Rule 

type Rule interface {
	// Text returns the original rule text
	Text() string

	// GetFilterListID returns ID of the filter list this rule belongs to
	GetFilterListID() int
}

Rule is a base interface for all filtering rules

func NewRule 

func NewRule(line string, filterListID int) (Rule, error)

NewRule creates a new filtering rule from the specified line It returns nil if the line is empty or if it is a comment

type RuleSyntaxError 

type RuleSyntaxError struct {
	// contains filtered or unexported fields
}

RuleSyntaxError represents an error while parsing a filtering rule

func (*RuleSyntaxError) Error 

func (e *RuleSyntaxError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.