blocker

package module
v0.0.0-...-ad81e3f Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2024 License: MIT Imports: 15 Imported by: 0

README 

#+TITLE: blocker - Domain blocker plugin for CoreDNS

=blocker= is a CoreDNS plugin which can be used to block a list of domains provided in the AdBlock
Plus syntax format. The blocklist will be loaded into memory at start-up and the file's modified
time will be checked periodically. When the blocklist file is updated, the in-memory blocklist will
be updated by scanning the blocklist file line-by-line.

Updating the blocklist file itself is beyond the scope of this plugin. I recommend a bash script
which downloads [[https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts][common]] [[http://hosts.oisd.nl/][blocklists]] and updates them into a format without comments. The script
[[file:blocklist-file-preparer.sh]] included with this repository is an example of how this can be done
using bash and common GNU utilities.

*Example blocklist file:* ([[https://github.com/AdguardTeam/AdGuardHome/wiki/Hosts-Blocklists#adblock-style][AdBlock Plus syntax]])

#+begin_src text
  ||buyer.revsci.net^
  ||ww92.impfr.tradedoubler.com^
  ||next.chartboost.com^
  ||pl16442154.alternativecpmgate.com^
  ||denturesauaid.com^
  ||pdx-p-con-336.saas.appdynamics.com^
  ||cdn.ad.citynews.it^
  ||xxxxxxxamob.acs86.com^
  ||www.globalhotsale.su^
  ||zipuploads.com^
#+end_src

* Usage

** CoreDNS Binary

You can include blocker in the CoreDNS code just as you would include any other CoreDNS plugin.

#+begin_src sh
  # Clone coredns to a local location
  $ git clone git@github.com:coredns/coredns.git ~/dns-server/coredns

  # Clone blocker plugin to a close location
  $ git clone git@github.com:icyflame/blocker.git ~/dns-server/blocker

  # Symlink blocker location into coredns/plugin/blocker
  $ cd ~/dns-server/coredns/plugin
  $ ln -s ../blocker ./blocker

  # Update plugin.cfg and put the line "blocker:blocker" before the "forward:forward" line

  # Build CoreDNS
  $ cd ~/dns-server/coredns
  $ go generate
  $ make
  $ ./coredns -conf Corefile
#+end_src

** Corefile

The =blocker= directive inside Corefile requires four arguments. The first argument is the absolute
path to the blocklist file. The second argument is the frequency at which the blocklist file is
checked for updates. The third argument is the type of blocklist file (=hosts= and =abp= are the
only two values which are supported at this time.)  The fourth argument is the response type from
the plugin, either =empty= for a valid DNS response with 0.0.0.0 or ::6 or =nxdomain= to respond
with a DNS empty response.

The frequency is specified as a string and the value should be a valid argument of the
[[https://pkg.go.dev/time#ParseDuration][time.ParseDuration]] function.

#+begin_src conf
  blocker /home/user/blocklist_file 1h abp empty
#+end_src

The following is a sample Corefile including the =blocker= directive. It will block domains that are
specified in the blocklist and forward everything else to a full DNS server.

#+begin_src conf
  .:53 {
	metadata

	# prometheus records metrics regarding incoming requests
	prometheus

	# log writes 1 line to the log for every DNS request
	# The last word in the log line will be YES if the request was blocked and NO if it was not
	# blocked.
	# This behaviour is supported by the metadata plugin.
	log . "{common} {/blocker/request-blocked}"

	# blocker blocks domains which are specified in the blocklist
	blocker /home/user/blocklist_file 1h abp empty

	# forward handles any request that is not blocked by blocker
	forward . 127.0.0.1:9053
  }
#+end_src

** plugin.cfg

This is a sample middleware configuration file. The order of plugins here is important. This is the
order in which plugins will be executed for incoming requests.

#+begin_src conf
  metadata:metadata
  prometheus:metrics
  log:log
  blocker:blocker
  forward:forward
#+end_src

* Interaction with Other CoreDNS Plugins

** =metadata=

The blocker plugin will write the metadata value with the label =blocker/request-blocked=. This is a
boolean value whose value will be either =YES= (if the request was blocked and the empty IP address
was returned as a result to the user) and =NO= when the request was not blocked.

* Release Binaries

For tags which are published to this repository, the GitHub Actions workflow
=./.github/workflows/build-binary.yml= builds binaries using the latest Go version for Linux under
the three most popular architectures: AMD64, ARM (32 bit), and ARM64. The =tar.gz= files contain a
Checksum file which can be used together with =sha256sum= to verify the integrity of the binary.

#+begin_src sh
  $ wget https://github.com/icyflame/blocker/releases/download/v0.0.1-alpha/coredns-linux-amd64.tar.gz
  ...
  coredns-linux-amd64.tar.gz            100%[=======================================================================>]   5.16M   610KB/s    in 14s

  2024-07-13 12:26:05 (390 KB/s) - ‘coredns-linux-amd64.tar.gz’ saved [5414731/5414731]

  $ tar tvf coredns-linux-amd64.tar.gz
  -rwxr-xr-x runner/docker 14110872 2024-07-13 12:26 coredns-linux-amd64
  -rw-r--r-- runner/docker       86 2024-07-13 12:26 coredns-linux-amd64.checksum

  $ tar zxf coredns-linux-amd64.tar.gz

  $ sha256sum -c coredns-linux-amd64.checksum
  coredns-linux-amd64: OK

  $ ./coredns-linux-amd64 -version
  CoreDNS-1.11.1
  linux/amd64, go1.22.5, Blocker plugin refs/tags/v0.0.1-alpha 1e6061ee8b7d2ad2ee5c632d3b91851c00481453
#+end_src

Documentation

Index

Constants

View Source 
const MetadataRequestBlocked = "blocker/request-blocked"
View Source 
const PluginName = "blocker"
View Source 
const RequiredArgs = 4

Variables

This section is empty.

Functions

func GetEmptyAnswerForQuestionType 

func GetEmptyAnswerForQuestionType(questionType uint16, domain string) dns.RR

GetEmptyAnswerForQuestionType ...

Types

type BlockDomainsDecider 

type BlockDomainsDecider interface {
	IsDomainBlocked(domain string) bool
	StartBlocklistUpdater(ticker *time.Ticker)
	UpdateBlocklist() error
}

BlockDomainsDecider is the interface which must be implemented by any type which intends to become a blocker. The purpose of each of the functions is described below.

func NewBlockDomainsDeciderABPFile 

func NewBlockDomainsDeciderABPFile(filePath string, logger Logger) BlockDomainsDecider

Name ...

func NewBlockDomainsDeciderABPUrl 

func NewBlockDomainsDeciderABPUrl(url string, logger Logger) BlockDomainsDecider

Name ...

func NewBlockDomainsDeciderHostsFile 

func NewBlockDomainsDeciderHostsFile(filePath string, logger Logger) BlockDomainsDecider

Name ...

func NewBlockDomainsDeciderHostsUrl 

func NewBlockDomainsDeciderHostsUrl(url string, logger Logger) BlockDomainsDecider

Name ...

func PrepareBlocklist 

func PrepareBlocklist(filePath string, blocklistUpdateFrequency string, blocklistType string, logger Logger) (BlockDomainsDecider, []func() error, error)

PrepareBlocklist ...

type BlockDomainsDeciderABP 

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

func (*BlockDomainsDeciderABP) IsBlocklistUpdateRequired 

func (d *BlockDomainsDeciderABP) IsBlocklistUpdateRequired() bool

IsBlocklistUpdateRequired ...

func (*BlockDomainsDeciderABP) IsDomainBlocked 

func (d *BlockDomainsDeciderABP) IsDomainBlocked(domain string) bool

IsDomainBlocked ...

func (*BlockDomainsDeciderABP) StartBlocklistUpdater 

func (d *BlockDomainsDeciderABP) StartBlocklistUpdater(ticker *time.Ticker)

StartBlocklistUpdater ...

func (*BlockDomainsDeciderABP) UpdateBlocklist 

func (d *BlockDomainsDeciderABP) UpdateBlocklist() error

UpdateBlocklist ...

type BlockDomainsDeciderABPUrl 

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

func (*BlockDomainsDeciderABPUrl) IsBlocklistUpdateRequired 

func (d *BlockDomainsDeciderABPUrl) IsBlocklistUpdateRequired() bool

IsBlocklistUpdateRequired ...

func (*BlockDomainsDeciderABPUrl) IsDomainBlocked 

func (d *BlockDomainsDeciderABPUrl) IsDomainBlocked(domain string) bool

IsDomainBlocked ...

func (*BlockDomainsDeciderABPUrl) StartBlocklistUpdater 

func (d *BlockDomainsDeciderABPUrl) StartBlocklistUpdater(ticker *time.Ticker)

StartBlocklistUpdater ...

func (*BlockDomainsDeciderABPUrl) UpdateBlocklist 

func (d *BlockDomainsDeciderABPUrl) UpdateBlocklist() error

UpdateBlocklist ...

type BlockDomainsDeciderHosts 

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

func (*BlockDomainsDeciderHosts) IsBlocklistUpdateRequired 

func (d *BlockDomainsDeciderHosts) IsBlocklistUpdateRequired() bool

IsBlocklistUpdateRequired ...

func (*BlockDomainsDeciderHosts) IsDomainBlocked 

func (d *BlockDomainsDeciderHosts) IsDomainBlocked(domain string) bool

IsDomainBlocked ...

func (*BlockDomainsDeciderHosts) StartBlocklistUpdater 

func (d *BlockDomainsDeciderHosts) StartBlocklistUpdater(ticker *time.Ticker)

StartBlocklistUpdater ...

func (*BlockDomainsDeciderHosts) UpdateBlocklist 

func (d *BlockDomainsDeciderHosts) UpdateBlocklist() error

UpdateBlocklist ...

type BlockDomainsDeciderHostsUrl 

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

func (*BlockDomainsDeciderHostsUrl) IsBlocklistUpdateRequired 

func (d *BlockDomainsDeciderHostsUrl) IsBlocklistUpdateRequired() bool

IsBlocklistUpdateRequired ...

func (*BlockDomainsDeciderHostsUrl) IsDomainBlocked 

func (d *BlockDomainsDeciderHostsUrl) IsDomainBlocked(domain string) bool

IsDomainBlocked ...

func (*BlockDomainsDeciderHostsUrl) StartBlocklistUpdater 

func (d *BlockDomainsDeciderHostsUrl) StartBlocklistUpdater(ticker *time.Ticker)

StartBlocklistUpdater ...

func (*BlockDomainsDeciderHostsUrl) UpdateBlocklist 

func (d *BlockDomainsDeciderHostsUrl) UpdateBlocklist() error

UpdateBlocklist ...

type Blocker 

type Blocker struct {
	Next         plugin.Handler
	Decider      BlockDomainsDecider
	ResponseType string
}

func (Blocker) Metadata 

func (b Blocker) Metadata(ctx context.Context, state request.Request) context.Context

Metadata implements the Metadata plugin's required interface in the blocker function.

func (Blocker) Name 

func (b Blocker) Name() string

Name ...

func (Blocker) ServeDNS 

func (b Blocker) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

type BlocklistType 

type BlocklistType string
const BlocklistType_ABP BlocklistType = "abp"
const BlocklistType_Hosts BlocklistType = "hosts"

type Logger 

type Logger interface {
	// Copied from the list of functions provided by https://pkg.go.dev/github.com/coredns/coredns/plugin/pkg/log
	Debug(v ...interface{})
	Debugf(format string, v ...interface{})
	Error(v ...interface{})
	Errorf(format string, v ...interface{})
	Fatal(v ...interface{})
	Fatalf(format string, v ...interface{})
	Info(v ...interface{})
	Infof(format string, v ...interface{})
	Warning(v ...interface{})
	Warningf(format string, v ...interface{})
}

type ResponseType 

type ResponseType string
const (
	ResponseType_Empty    ResponseType = "empty"
	ResponseType_NXDOMAIN ResponseType = "nxdomain"
)

Source Files

View all Source files

Directories

Path Synopsis

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.