dnsfilter

package
v0.105.2 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2021 License: GPL-3.0 Imports: 27 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 %q: %s", host, err)
    }
    if res.IsFiltered {
        log.Printf("Host %s is filtered, reason - %q, matched rule: %q", host, res.Reason, res.Rule)
    } else {
        log.Printf("Host %s is not filtered, reason - %q", 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 %q: %s", host, err)
    }
    if res.IsFiltered {
        log.Printf("Host %s is filtered, reason - %q, matched rule: %q", host, res.Reason, res.Rule)
    } else {
        log.Printf("Host %s is not filtered, reason - %q", host, res.Reason)
    }
}

Documentation

Overview

Package dnsfilter implements a DNS request and response filter.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BlockedSvcKnown 

func BlockedSvcKnown(s string) bool

BlockedSvcKnown - return TRUE if a blocked service name is known

func InitModule 

func InitModule()

InitModule manually initializes 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:"-"`

	// CustomResolver is the resolver used by DNSFilter.
	CustomResolver Resolver
}

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

type DNSFilter added in v0.105.0 

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

DNSFilter matches hostnames and DNS requests against filtering 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.105.0 

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

ApplyBlockedServices - set blocked services settings for this DNS request

func (*DNSFilter) CheckHost added in v0.105.0 

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 control rules, if they are enabled.

func (*DNSFilter) CheckHostRules added in v0.105.0 

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.105.0 

func (d *DNSFilter) Close()

Close - close the object

func (*DNSFilter) GetConfig added in v0.105.0 

func (d *DNSFilter) GetConfig() RequestFilteringSettings

GetConfig - get configuration

func (*DNSFilter) SafeSearchDomain added in v0.105.0 

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

SafeSearchDomain returns replacement address for search engine

func (*DNSFilter) SetFilters added in v0.105.0 

func (d *DNSFilter) SetFilters(blockFilters, 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) SetParentalUpstream added in v0.105.0 

func (d *DNSFilter) SetParentalUpstream(u upstream.Upstream)

SetParentalUpstream sets the parental upstream for *DNSFilter.

TODO(e.burkov): Remove this in v1 API to forbid the direct access.

func (*DNSFilter) SetSafeBrowsingUpstream added in v0.105.0 

func (d *DNSFilter) SetSafeBrowsingUpstream(u upstream.Upstream)

SetSafeBrowsingUpstream sets the safe browsing upstream for *DNSFilter.

TODO(e.burkov): Remove this in v1 API to forbid the direct access.

func (*DNSFilter) Start added in v0.105.0 

func (d *DNSFilter) Start()

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

func (*DNSFilter) WriteDiskConfig added in v0.105.0 

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

WriteDiskConfig - write configuration

type DNSRewriteResult added in v0.105.0 

type DNSRewriteResult struct {
	Response DNSRewriteResultResponse `json:",omitempty"`
	RCode    rules.RCode              `json:",omitempty"`
}

DNSRewriteResult is the result of application of $dnsrewrite rules.

type DNSRewriteResultResponse added in v0.105.0 

type DNSRewriteResultResponse map[rules.RRType][]rules.RRValue

DNSRewriteResultResponse is the collection of DNS response records the server returns.

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
	// NotFilteredAllowList - the host is explicitly allowed
	NotFilteredAllowList
	// NotFilteredError is returned when there was an error during
	// checking.  Reserved, currently unused.
	NotFilteredError

	// FilteredBlockList - the host was matched to be advertising host
	FilteredBlockList
	// 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

	// Rewritten is returned when there was a rewrite by a legacy DNS
	// rewrite rule.
	Rewritten

	// RewrittenAutoHosts is returned when there was a rewrite by autohosts
	// rules (/etc/hosts and so on).
	RewrittenAutoHosts

	// RewrittenRule is returned when a $dnsrewrite filter rule was applied.
	//
	// TODO(a.garipov): Remove Rewritten and RewrittenAutoHosts by merging
	// their functionality into RewrittenRule.
	//
	// See https://github.com/AdguardTeam/AdGuardHome/issues/2499.
	RewrittenRule
)

func (Reason) In added in v0.105.0 

func (r Reason) In(reasons ...Reason) bool

In returns true if reasons include r.

func (Reason) Matched 

func (r Reason) Matched() bool

Matched returns true if any match at all was found regardless of whether it was 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   net.IP
	ClientTags []string

	ServicesRules []ServiceEntry
}

RequestFilteringSettings is custom filtering settings

type Resolver added in v0.105.0 

type Resolver interface {
	// TODO(e.burkov): Replace with LookupIP after upgrading go to v1.15.
	LookupIPAddr(ctx context.Context, host string) (ips []net.IPAddr, err error)
}

Resolver is the interface for net.Resolver to simplify testing.

type Result 

type Result struct {
	// IsFiltered is true if the request is filtered.
	IsFiltered bool `json:",omitempty"`

	// Reason is the reason for blocking or unblocking the request.
	Reason Reason `json:",omitempty"`

	// Rules are applied rules.  If Rules are not empty, each rule
	// is not nil.
	Rules []*ResultRule `json:",omitempty"`

	// ReverseHosts is the reverse lookup rewrite result.  It is
	// empty unless Reason is set to RewrittenAutoHosts.
	ReverseHosts []string `json:",omitempty"`

	// IPList is the lookup rewrite result.  It is empty unless
	// Reason is set to RewrittenAutoHosts or Rewritten.
	IPList []net.IP `json:",omitempty"`

	// CanonName is the CNAME value from the lookup rewrite result.
	// It is empty unless Reason is set to Rewritten or RewrittenRule.
	CanonName string `json:",omitempty"`

	// ServiceName is the name of the blocked service.  It is empty
	// unless Reason is set to FilteredBlockedService.
	ServiceName string `json:",omitempty"`

	// DNSRewriteResult is the $dnsrewrite filter rule result.
	DNSRewriteResult *DNSRewriteResult `json:",omitempty"`
}

Result contains the result of a request check.

All fields transitively have omitempty tags so that the query log doesn't become too large.

TODO(a.garipov): Clarify relationships between fields. Perhaps replace with a sum type or an interface?

type ResultRule added in v0.105.0 

type ResultRule struct {
	// FilterListID is the ID of the rule's filter list.
	FilterListID int64 `json:",omitempty"`
	// Text is the text of the rule.
	Text string `json:",omitempty"`
	// IP is the host IP.  It is nil unless the rule uses the
	// /etc/hosts syntax or the reason is FilteredSafeSearch.
	IP net.IP `json:",omitempty"`
}

ResultRule contains information about applied rules.

type RewriteEntry 

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 

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.