dnsfilter

package
v0.104.0 Latest Latest
Warning

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

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

README

AdGuard Home's DNS filtering go library

Example use:

[ -z "$GOPATH" ] && export GOPATH=$HOME/go
go get -d github.com/AdguardTeam/AdGuardHome/dnsfilter

Create file filter.go

package main

import (
    "github.com/AdguardTeam/AdGuardHome/dnsfilter"
    "log"
)

func main() {
    filter := dnsfilter.New()
    filter.AddRule("||dou*ck.net^")
    host := "www.doubleclick.net"
    res, err := filter.CheckHost(host)
    if err != nil {
        // temporary failure
        log.Fatalf("Failed to check host '%s': %s", host, err)
    }
    if res.IsFiltered {
        log.Printf("Host %s is filtered, reason - '%s', matched rule: '%s'", host, res.Reason, res.Rule)
    } else {
        log.Printf("Host %s is not filtered, reason - '%s'", host, res.Reason)
    }
}

And then run it:

go run filter.go

You will get:

2000/01/01 00:00:00 Host www.doubleclick.net is filtered, reason - 'FilteredBlackList', matched rule: '||dou*ck.net^'

You can also enable checking against AdGuard's SafeBrowsing:

package main

import (
    "github.com/AdguardTeam/AdGuardHome/dnsfilter"
    "log"
)

func main() {
    filter := dnsfilter.New()
    filter.EnableSafeBrowsing()
    host := "wmconvirus.narod.ru" // hostname for testing safebrowsing
    res, err := filter.CheckHost(host)
    if err != nil {
        // temporary failure
        log.Fatalf("Failed to check host '%s': %s", host, err)
    }
    if res.IsFiltered {
        log.Printf("Host %s is filtered, reason - '%s', matched rule: '%s'", host, res.Reason, res.Rule)
    } else {
        log.Printf("Host %s is not filtered, reason - '%s'", host, res.Reason)
    }
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BlockedSvcKnown added in v0.102.0 

func BlockedSvcKnown(s string) bool

BlockedSvcKnown - return TRUE if a blocked service name is known

func InitModule added in v0.102.0 

func InitModule()

InitModule() - manually initialize blocked services map

Types

type Config 

type Config struct {
	ParentalEnabled     bool   `yaml:"parental_enabled"`
	SafeSearchEnabled   bool   `yaml:"safesearch_enabled"`
	SafeBrowsingEnabled bool   `yaml:"safebrowsing_enabled"`
	ResolverAddress     string `yaml:"-"` // DNS server address

	SafeBrowsingCacheSize uint `yaml:"safebrowsing_cache_size"` // (in bytes)
	SafeSearchCacheSize   uint `yaml:"safesearch_cache_size"`   // (in bytes)
	ParentalCacheSize     uint `yaml:"parental_cache_size"`     // (in bytes)
	CacheTime             uint `yaml:"cache_time"`              // Element's TTL (in minutes)

	Rewrites []RewriteEntry `yaml:"rewrites"`

	// Names of services to block (globally).
	// Per-client settings can override this configuration.
	BlockedServices []string `yaml:"blocked_services"`

	// IP-hostname pairs taken from system configuration (e.g. /etc/hosts) files
	AutoHosts *util.AutoHosts `yaml:"-"`

	// Called when the configuration is changed by HTTP request
	ConfigModified func() `yaml:"-"`

	// Register an HTTP handler
	HTTPRegister func(string, string, func(http.ResponseWriter, *http.Request)) `yaml:"-"`
}

Config allows you to configure DNS filtering with New() or just change variables directly.

type Dnsfilter 

type Dnsfilter struct {
	Config // for direct access by library users, even a = assignment
	// contains filtered or unexported fields
}

Dnsfilter holds added rules and performs hostname matches against the rules

func New 

func New(c *Config, blockFilters []Filter) *Dnsfilter

New creates properly initialized DNS Filter that is ready to be used

func (*Dnsfilter) ApplyBlockedServices added in v0.102.0 

func (d *Dnsfilter) ApplyBlockedServices(setts *RequestFilteringSettings, list []string, global bool)

ApplyBlockedServices - set blocked services settings for this DNS request

func (*Dnsfilter) CheckHost 

func (d *Dnsfilter) CheckHost(host string, qtype uint16, setts *RequestFilteringSettings) (Result, error)

CheckHost tries to match the host against filtering rules, then safebrowsing and parental if they are enabled

func (*Dnsfilter) CheckHostRules added in v0.100.7 

func (d *Dnsfilter) CheckHostRules(host string, qtype uint16, setts *RequestFilteringSettings) (Result, error)

CheckHostRules tries to match the host against filtering rules only

func (*Dnsfilter) Close added in v0.99.0 

func (d *Dnsfilter) Close()

Close - close the object

func (*Dnsfilter) GetConfig added in v0.99.0 

func (d *Dnsfilter) GetConfig() RequestFilteringSettings

GetConfig - get configuration

func (*Dnsfilter) GetStats 

func (d *Dnsfilter) GetStats() Stats

GetStats return dns filtering stats since startup

func (*Dnsfilter) SafeSearchDomain 

func (d *Dnsfilter) SafeSearchDomain(host string) (string, bool)

SafeSearchDomain returns replacement address for search engine

func (*Dnsfilter) SetFilters added in v0.99.0 

func (d *Dnsfilter) SetFilters(blockFilters []Filter, allowFilters []Filter, async bool) error

SetFilters - set new filters (synchronously or asynchronously) When filters are set asynchronously, the old filters continue working until the new filters are ready. 

In this case the caller must ensure that the old filter files are intact.

func (*Dnsfilter) Start added in v0.101.0 

func (d *Dnsfilter) Start()

Start - start the module: . start async filtering initializer goroutine . register web handlers

func (*Dnsfilter) WriteDiskConfig added in v0.99.0 

func (d *Dnsfilter) WriteDiskConfig(c *Config)

WriteDiskConfig - write configuration

type Filter 

type Filter struct {
	ID       int64  // auto-assigned when filter is added (see nextFilterID)
	Data     []byte `yaml:"-"` // List of rules divided by '\n'
	FilePath string `yaml:"-"` // Path to a filtering rules file
}

Filter represents a filter list

type LookupStats 

type LookupStats struct {
	Requests   uint64 // number of HTTP requests that were sent
	CacheHits  uint64 // number of lookups that didn't need HTTP requests
	Pending    int64  // number of currently pending HTTP requests
	PendingMax int64  // maximum number of pending HTTP requests
}

LookupStats store stats collected during safebrowsing or parental checks

type Reason 

type Reason int

Reason holds an enum detailing why it was filtered or not filtered 

const (

	// NotFilteredNotFound - host was not find in any checks, default value for result
	NotFilteredNotFound Reason = iota
	// NotFilteredWhiteList - the host is explicitly whitelisted
	NotFilteredWhiteList
	// NotFilteredError - there was a transitive error during check
	NotFilteredError

	// FilteredBlackList - the host was matched to be advertising host
	FilteredBlackList
	// FilteredSafeBrowsing - the host was matched to be malicious/phishing
	FilteredSafeBrowsing
	// FilteredParental - the host was matched to be outside of parental control settings
	FilteredParental
	// FilteredInvalid - the request was invalid and was not processed
	FilteredInvalid
	// FilteredSafeSearch - the host was replaced with safesearch variant
	FilteredSafeSearch
	// FilteredBlockedService - the host is blocked by "blocked services" settings
	FilteredBlockedService

	// ReasonRewrite - rewrite rule was applied
	ReasonRewrite

	// RewriteEtcHosts - rewrite by /etc/hosts rule
	RewriteEtcHosts
)

func (Reason) Matched 

func (r Reason) Matched() bool

Matched can be used to see if any match at all was found, no matter filtered or not

func (Reason) String 

func (r Reason) String() string

type RequestFilteringSettings 

type RequestFilteringSettings struct {
	FilteringEnabled    bool
	SafeSearchEnabled   bool
	SafeBrowsingEnabled bool
	ParentalEnabled     bool

	ClientName string
	ClientIP   string
	ClientTags []string

	ServicesRules []ServiceEntry
}

RequestFilteringSettings is custom filtering settings

type Result 

type Result struct {
	IsFiltered bool   `json:",omitempty"` // True if the host name is filtered
	Reason     Reason `json:",omitempty"` // Reason for blocking / unblocking
	Rule       string `json:",omitempty"` // Original rule text
	IP         net.IP `json:",omitempty"` // Not nil only in the case of a hosts file syntax
	FilterID   int64  `json:",omitempty"` // Filter ID the rule belongs to

	// for ReasonRewrite:
	CanonName string `json:",omitempty"` // CNAME value

	// for RewriteEtcHosts:
	ReverseHost string `json:",omitempty"`

	// for ReasonRewrite & RewriteEtcHosts:
	IPList []net.IP `json:",omitempty"` // list of IP addresses

	// for FilteredBlockedService:
	ServiceName string `json:",omitempty"` // Name of the blocked service
}

Result holds state of hostname check

type RewriteEntry added in v0.98.0 

type RewriteEntry struct {
	Domain string `yaml:"domain"`
	Answer string `yaml:"answer"` // IP address or canonical name
	Type   uint16 `yaml:"-"`      // DNS record type: CNAME, A or AAAA
	IP     net.IP `yaml:"-"`      // Parsed IP address (if Type is A or AAAA)
}

RewriteEntry is a rewrite array element

type ServiceEntry added in v0.98.0 

type ServiceEntry struct {
	Name  string
	Rules []*rules.NetworkRule
}

ServiceEntry - blocked service array element

type Stats 

type Stats struct {
	Safebrowsing LookupStats
	Parental     LookupStats
	Safesearch   LookupStats
}

Stats store LookupStats for safebrowsing, parental and safesearch

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.