rules

package
v0.20.0 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2024 License: GPL-3.0 Imports: 13 Imported by: 7

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.Error = "the rule is too wide, add domain, denyallow, client, " +
	"or ctag restrictions or make it more specific"

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

View Source 
var ErrUnsupportedRule errors.Error = "this type of rules is unsupported"

ErrUnsupportedRule signals that this might be a valid rule type, but it is not yet supported by this library

Functions

func FillRequestForHostname added in v0.17.1 

func FillRequestForHostname(r *Request, hostname string)

FillRequestForHostname fills an instance of request r for matching the hostname. It uses "http://" as a protocol for request URL and TypeDocument as request type.

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 is the original rule text.
	RuleText string

	// 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

	// FilterListID is a list identifier.
	FilterListID int

	// Type of the rule.
	Type CosmeticRuleType

	// 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, see 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 DNSMX added in v0.14.1 

type DNSMX struct {
	Exchange   string
	Preference uint16
}

DNSMX is the type of RRValue values returned for MX records in DNS rewrites.

type DNSRewrite added in v0.14.0 

type DNSRewrite struct {
	// Value is the value for the record.  See [RRValue] documentation for more
	// details.
	Value RRValue

	// NewCNAME is the new CNAME.  If set, clients must ignore other fields,
	// resolve the CNAME, and set the new records accordingly.
	NewCNAME string

	// RCode is the new DNS RCODE.
	RCode RCode

	// RRType is the new DNS resource record (RR) type.  It is only non-zero
	// if RCode is dns.RCodeSuccess.
	RRType RRType
}

DNSRewrite is a DNS rewrite ($dnsrewrite) rule.

type DNSSRV added in v0.14.4 

type DNSSRV struct {
	Target   string
	Priority uint16
	Weight   uint16
	Port     uint16
}

DNSSRV is the type of RRValue values returned for SRV records in DNS rewrites.

type DNSSVCB added in v0.14.1 

type DNSSVCB struct {
	Params   map[string]string
	Target   string
	Priority uint16
}

DNSSVCB is the type of RRValue values returned for HTTPS and SVCB records in dns rewrites.

See https://tools.ietf.org/html/draft-ietf-dnsop-svcb-https-02.

type HostRule 

type HostRule struct {
	// IP is the address of the rule.
	IP netip.Addr

	// RuleText is the original text of the rule.
	RuleText string

	// Hostnames is the slice of hostnames associated with IP.
	Hostnames []string

	// FilterListID is the identifier of the filter, containing the rule.
	FilterListID int
}

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) (h *HostRule, err 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 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

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

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, sourceRules []*NetworkRule) (result *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 {

	// DNSRewrite is the DNS rewrite rule, if any.
	DNSRewrite *DNSRewrite

	// RuleText is the original rule text.
	RuleText string
	// Shortcut is the longest substring of the rule pattern with no special
	// characters.
	Shortcut string

	// Mutex protects the fields.
	sync.Mutex

	// FilterListID is a filter list identifier.
	FilterListID int

	// Whitelist is true if this is an exception rule.
	Whitelist bool
	// 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 GetDNSBasicRule added in v0.17.1 

func GetDNSBasicRule(rules []*NetworkRule) (basicRule *NetworkRule)

GetDNSBasicRule returns a rule that should be applied to the DNS request.

func NewNetworkRule 

func NewNetworkRule(ruleText string, filterListID int) (r *NetworkRule, err 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() (ok bool)

IsRegexRule returns true if the rule is a regular expression rule

func (*NetworkRule) Match 

func (f *NetworkRule) Match(r *Request) (ok 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 RCode added in v0.14.0 

type RCode = int

RCode is a semantic alias for int when used as a DNS response code RCODE.

type RRType added in v0.14.0 

type RRType = uint16

RRType is a semantic alias for uint16 when used as a DNS resource record (RR) type.

type RRValue added in v0.14.0 

type RRValue = any

RRValue is the value of a resource record. Depending on the RRType, it will have different types:

type Request 

type Request struct {
	// ClientIP is the IP address to match against $client modifiers.  The
	// default zero value won't be considered.
	ClientIP netip.Addr

	// ClientName is the name to match against $client modifiers.  The default
	// empty value won't be considered.
	ClientName string

	// URL is the full request URL.
	URL string

	// URLLowerCase is the full request URL in lower case.
	URLLowerCase string

	// Hostname is the hostname to filter.
	Hostname string

	// Domain is the effective top-level domain of the request with an
	// additional label.
	Domain string

	// SourceURL is the full URL of the source.
	SourceURL string

	// SourceHostname is the hostname of the source.
	SourceHostname string

	// SourceDomain is the effective top-level domain of the source with an
	// additional label.
	SourceDomain string

	// SortedClientTags is the list of tags to match against $ctag modifiers.
	SortedClientTags []string

	// RequestType is the type of the filtering request.
	RequestType RequestType

	// DNSType is the type of the resource record (RR) of a DNS request, for
	// example "A" or "AAAA".  See [RRValue] for all acceptable constants and
	// their corresponding values.
	DNSType uint16

	// ThirdParty is true if the filtering request should consider $third-party
	// modifier.
	ThirdParty bool

	// 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, for HTTP CONNECT, or for SNI matching.
	IsHostnameRequest bool
}

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

func NewRequest 

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

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

func NewRequestForHostname 

func NewRequestForHostname(hostname string) (r *Request)

NewRequestForHostname creates a new instance of Request for matching the 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
	// TypePing (navigator.sendBeacon() or ping attribute on links) $ping
	TypePing
	// TypeOther - any other request type
	TypeOther
)

func (RequestType) Count 

func (t RequestType) Count() int

Count returns the 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) (r Rule, err 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.