dnsbl2

README

caddy-http-matchers-dnsbl2

caddy-http-matchers-dnsbl2 is a Caddy HTTP request matcher that checks the client IP address against one or more DNS blocklists (DNSBLs). The matcher is true when any configured provider returns an A record.

Features

• Queries all configured providers concurrently.
• Applies one timeout to the whole group of lookups. The default is 2 seconds.
• Cancels outstanding lookups as soon as one provider reports a match.
• Fails open on DNS errors. NXDOMAIN, SERVFAIL, timeouts, and other resolver errors are treated as not listed.
• Supports IPv4 and IPv6 DNSBL query formats.
• Uses Caddy's resolved client IP, including its trusted proxy configuration.

The matcher waits for the DNSBL result for the request being evaluated, but it does not use a global lock or block Caddy from serving other requests.

Build

Build Caddy with this module using xcaddy:

xcaddy build --with github.com/gslin/caddy-http-matchers-dnsbl2

Caddyfile

wiki.gslin.org {
        @badactors dnsbl2 {
                providers "b.barracudacentral.org." "spam.spamrats.com."
        }
        respond @badactors 403
}

An optional timeout can be configured with a Go duration:

@badactors dnsbl2 {
        providers "b.barracudacentral.org." "spam.spamrats.com."
        timeout 3s
}

At least one provider is required. Provider names may be written with or without a trailing dot.

JSON

The module ID is http.matchers.dnsbl2. A matcher in native Caddy JSON has the following shape:

{
  "dnsbl2": {
    "providers": [
      "b.barracudacentral.org.",
      "spam.spamrats.com."
    ],
    "timeout": "3s"
  }
}

Resolver behavior

Queries use the resolver configured for the operating system. Some DNSBL providers reject queries sent through shared public resolvers. A local recursive resolver may be required in that case.

DNS lookup failures are fail-open by design. They are logged at debug level and do not cause Caddy to return an HTTP 500 response.

Development

go test ./...

Documentation

Overview

Package dnsbl2 provides a Caddy HTTP request matcher backed by DNS blocklists.

Index

• type MatchDNSBL
  • func (MatchDNSBL) CaddyModule() caddy.ModuleInfo
  • func (m *MatchDNSBL) Match(r *http.Request) bool
  • func (m *MatchDNSBL) MatchWithError(r *http.Request) (bool, error)
  • func (m *MatchDNSBL) Provision(ctx caddy.Context) error
  • func (m *MatchDNSBL) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (m *MatchDNSBL) Validate() error

Types

type MatchDNSBL

type MatchDNSBL struct {
	// Providers is the list of DNSBL zones to query.
	Providers []string `json:"providers,omitempty"`

	// Timeout limits the total time spent checking all providers for a request.
	// The default is 2 seconds.
	Timeout caddy.Duration `json:"timeout,omitempty"`
	// contains filtered or unexported fields
}

MatchDNSBL matches requests whose client IP is listed by at least one DNSBL provider.

func (MatchDNSBL) CaddyModule

func (MatchDNSBL) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*MatchDNSBL) Match

func (m *MatchDNSBL) Match(r *http.Request) bool

Match reports whether the request matches. It is retained for compatibility with Caddy versions that use caddyhttp.RequestMatcher.

func (*MatchDNSBL) MatchWithError

func (m *MatchDNSBL) MatchWithError(r *http.Request) (bool, error)

MatchWithError reports whether the request's client IP is listed by any configured provider. DNS errors fail open and do not match.

func (*MatchDNSBL) Provision

func (m *MatchDNSBL) Provision(ctx caddy.Context) error

Provision prepares the matcher for use.

func (*MatchDNSBL) UnmarshalCaddyfile

func (m *MatchDNSBL) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler. Syntax:

dnsbl2 {
	providers <zones...>
	timeout <duration>
}

func (*MatchDNSBL) Validate

func (m *MatchDNSBL) Validate() error

Validate validates the matcher configuration.