resolve

README

Leverage Many Recursive DNS Servers

Designed to support DNS brute-forcing with minimal system resources:

• Easy to send a large number of queries concurrently
• Hundreds of DNS nameservers can easily be leveraged
• A minimal number of goroutines are employed by the package
• Provides features like DNS wildcard detection and NSEC traversal

Installation

go get -v -u github.com/caffix/resolve@master

Usage

qps := 15
var nameservers = []string{
	"8.8.8.8",        // Google
	"1.1.1.1",        // Cloudflare
	"9.9.9.9",        // Quad9
	"208.67.222.222", // Cisco OpenDNS
	"84.200.69.80",   // DNS.WATCH
	"64.6.64.6",      // Neustar DNS
	"8.26.56.26",     // Comodo Secure DNS
	"205.171.3.65",   // Level3
	"134.195.4.2",    // OpenNIC
	"185.228.168.9",  // CleanBrowsing
	"76.76.19.19",    // Alternate DNS
	"37.235.1.177",   // FreeDNS
	"77.88.8.1",      // Yandex.DNS
	"94.140.14.140",  // AdGuard
	"38.132.106.139", // CyberGhost
	"74.82.42.42",    // Hurricane Electric
	"76.76.2.0",      // ControlD
}
r := resolve.NewResolvers()
_ = r.AddResolvers(qps, nameservers...)
defer r.Stop()

ctx, cancel := context.WithTimeout(context.Background(), 30 * time.Second)
defer cancel()

ch := make(chan *dns.Msg, 100)
go func() {
	for _, name := range names {
		r.Query(ctx, resolve.QueryMsg(name, 1), ch)
	}
}()

for {
	select {
	case <-ctx.Done():
		return
	case resp := <-ch:
		if resp.Rcode == dns.RcodeSuccess && len(resp.Answer) > 0 {
			ans := ExtractAnswers(resp)
			domain, err := publicsuffix.EffectiveTLDPlusOne(ans[0].Name)

			if err == nil && !r.WildcardDetected(ctx, resp, domain) {
				fmt.Printf("%s resolved to %s\n", ans[0].Name, ans[0].Data)
			}
		}
	}
}

Licensing

This program is free software: you can redistribute it and/or modify it under the terms of the Apache license.

Documentation

Index

• Constants
• func BackoffJitter(min, max time.Duration) time.Duration
• func ExponentialBackoff(events int, delay time.Duration) time.Duration
• func FQDNToRegistered(fqdn, registered string, callback func(domain string) bool)
• func FirstProperSubdomain(ctx context.Context, r *Resolvers, name string) string
• func QueryMsg(name string, qtype uint16) *dns.Msg
• func RegisteredToFQDN(registered, fqdn string, callback func(domain string) bool)
• func RemoveLastDot(name string) string
• func ReverseMsg(addr string) *dns.Msg
• func SetupOptions() *dns.OPT
• func TruncatedExponentialBackoff(events int, delay, max time.Duration) time.Duration
• func UnlikelyName(sub string) string
• func WalkMsg(name string, qtype uint16) *dns.Msg
• type ExtractedAnswer
  • func AnswersByType(answers []*ExtractedAnswer, qtype uint16) []*ExtractedAnswer
  • func ExtractAnswers(msg *dns.Msg) []*ExtractedAnswer
• type RateTracker
  • func NewRateTracker() *RateTracker
  • func (r *RateTracker) Stop()
  • func (r *RateTracker) Success(sub string)
  • func (r *RateTracker) Take(sub string)
  • func (r *RateTracker) Timeout(sub string)
• type Resolvers
  • func NewResolvers() *Resolvers
  • func (r *Resolvers) AddResolvers(qps int, addrs ...string) error
  • func (r *Resolvers) ClientSubnetCheck()
  • func (r *Resolvers) Len() int
  • func (r *Resolvers) NsecTraversal(ctx context.Context, domain string) ([]*dns.NSEC, error)
  • func (r *Resolvers) QPS() int
  • func (r *Resolvers) Query(ctx context.Context, msg *dns.Msg, ch chan *dns.Msg)
  • func (r *Resolvers) QueryBlocking(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)
  • func (r *Resolvers) QueryChan(ctx context.Context, msg *dns.Msg) chan *dns.Msg
  • func (r *Resolvers) SetDetectionResolver(qps int, addr string)
  • func (r *Resolvers) SetLogger(l *log.Logger)
  • func (r *Resolvers) SetMaxQPS(qps int)
  • func (r *Resolvers) SetRateTracker(rt *RateTracker)
  • func (r *Resolvers) SetThresholdOptions(opt *ThresholdOptions)
  • func (r *Resolvers) SetTimeout(d time.Duration)
  • func (r *Resolvers) Stop()
  • func (r *Resolvers) WildcardDetected(ctx context.Context, resp *dns.Msg, domain string) bool
• type ThresholdOptions

Constants

const (
	MaxDNSNameLen  = 253
	MaxDNSLabelLen = 63
	MinLabelLen    = 6
	MaxLabelLen    = 24
	LDHChars       = "abcdefghijklmnopqrstuvwxyz0123456789-"
)

Constants related to DNS labels.

const DefaultTimeout = 2 * time.Second

DefaultTimeout is the duration waited until a DNS query expires.

const RcodeNoResponse int = 50

RcodeNoResponse is a special status code used to indicate no response or package error.

Functions

func BackoffJitter

func BackoffJitter(min, max time.Duration) time.Duration

BackoffJitter returns a random Duration between the provided min and max parameters.

func ExponentialBackoff

func ExponentialBackoff(events int, delay time.Duration) time.Duration

ExponentialBackoff returns a Duration equal to 2^events multiplied by the provided delay and jitter added equal to [0,delay).

func FQDNToRegistered

func FQDNToRegistered(fqdn, registered string, callback func(domain string) bool)

FQDNToRegistered executes the provided callback routine for domain names, starting with the FQDN to the registered domain name, removing one label with each execution. The process stops if the callback routine returns true, indicating completion.

func FirstProperSubdomain

func FirstProperSubdomain(ctx context.Context, r *Resolvers, name string) string

FirstProperSubdomain returns the first subdomain name using the provided name and Resolver that responds successfully to a DNS query for the NS record type.

func QueryMsg

func QueryMsg(name string, qtype uint16) *dns.Msg

QueryMsg generates a message used for a forward DNS query.

func RegisteredToFQDN

func RegisteredToFQDN(registered, fqdn string, callback func(domain string) bool)

RegisteredToFQDN executes the provided callback routine for domain names, starting with the registered domain name to the FQDN, adding one label with each execution. The process stops if the callback routine returns true, indicating completion.

func RemoveLastDot

func RemoveLastDot(name string) string

RemoveLastDot removes the '.' at the end of the provided FQDN.

func ReverseMsg

func ReverseMsg(addr string) *dns.Msg

ReverseMsg generates a message used for a reverse DNS query.

func SetupOptions

func SetupOptions() *dns.OPT

SetupOptions returns the EDNS0_SUBNET option for hiding our location.

func TruncatedExponentialBackoff

func TruncatedExponentialBackoff(events int, delay, max time.Duration) time.Duration

TruncatedExponentialBackoff returns a Duration equal to ExponentialBackoff with a provided maximum Duration used to truncate the result.

func UnlikelyName

func UnlikelyName(sub string) string

UnlikelyName takes a subdomain name and returns an unlikely DNS name within that subdomain.

func WalkMsg

func WalkMsg(name string, qtype uint16) *dns.Msg

WalkMsg generates a message used for a NSEC walk query.

Types

type ExtractedAnswer

type ExtractedAnswer struct {
	Name string
	Type uint16
	Data string
}

ExtractedAnswer contains information from the DNS response Answer section.

func AnswersByType

func AnswersByType(answers []*ExtractedAnswer, qtype uint16) []*ExtractedAnswer

AnswersByType returns only the answers from the DNS Answer section matching the provided type.

func ExtractAnswers

func ExtractAnswers(msg *dns.Msg) []*ExtractedAnswer

ExtractAnswers returns information from the DNS Answer section of the provided Msg in ExtractedAnswer type.

type RateTracker

type RateTracker struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewRateTracker

func NewRateTracker() *RateTracker

NewRateTracker returns an active RateTracker that tracks and rate limits per name server.

func (*RateTracker) Stop

func (r *RateTracker) Stop()

Stop will release the RateTracker resources.

func (*RateTracker) Success

func (r *RateTracker) Success(sub string)

Success signals to the RateTracker that a request for the provided subdomain name was successful.

func (*RateTracker) Take

func (r *RateTracker) Take(sub string)

Take blocks as required by the implemented rate limiter for the associated name server.

func (*RateTracker) Timeout

func (r *RateTracker) Timeout(sub string)

Timeout signals to the RateTracker that a request for the provided subdomain name timed out.

type Resolvers

type Resolvers struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Resolvers is a pool of DNS resolvers managed for brute forcing using random selection.

func NewResolvers

func NewResolvers() *Resolvers

NewResolvers initializes a Resolvers.

func (*Resolvers) AddResolvers

func (r *Resolvers) AddResolvers(qps int, addrs ...string) error

AddResolvers initializes and adds new resolvers to the pool of resolvers.

func (*Resolvers) ClientSubnetCheck

func (r *Resolvers) ClientSubnetCheck()

ClientSubnetCheck ensures that all the resolvers in the pool respond to the query and do not send the EDNS client subnet information.

func (*Resolvers) Len

func (r *Resolvers) Len() int

Len returns the number of resolvers that have been added to the pool.

func (*Resolvers) NsecTraversal

func (r *Resolvers) NsecTraversal(ctx context.Context, domain string) ([]*dns.NSEC, error)

NsecTraversal attempts to retrieve a DNS zone using NSEC-walking.

func (*Resolvers) QPS

func (r *Resolvers) QPS() int

QPS returns the maximum queries per second provided by the resolver pool.

func (*Resolvers) Query

func (r *Resolvers) Query(ctx context.Context, msg *dns.Msg, ch chan *dns.Msg)

Query queues the provided DNS message and returns the response on the provided channel.

func (*Resolvers) QueryBlocking

func (r *Resolvers) QueryBlocking(ctx context.Context, msg *dns.Msg) (*dns.Msg, error)

Query queues the provided DNS message and returns the associated response message.

func (*Resolvers) QueryChan

func (r *Resolvers) QueryChan(ctx context.Context, msg *dns.Msg) chan *dns.Msg

Query queues the provided DNS message and sends the response on the returned channel.

func (*Resolvers) SetDetectionResolver

func (r *Resolvers) SetDetectionResolver(qps int, addr string)

SetDetectionResolver sets the provided DNS resolver as responsible for wildcard detection.

func (*Resolvers) SetLogger

func (r *Resolvers) SetLogger(l *log.Logger)

SetLogger assigns a new logger to the resolver pool.

func (*Resolvers) SetMaxQPS

func (r *Resolvers) SetMaxQPS(qps int)

SetMaxQPS allows a preferred maximum number of queries per second to be specified for the pool.

func (*Resolvers) SetRateTracker

func (r *Resolvers) SetRateTracker(rt *RateTracker)

func (*Resolvers) SetThresholdOptions

func (r *Resolvers) SetThresholdOptions(opt *ThresholdOptions)

SetThresholdOptions updates the settings used for discontinuing use of a resolver due to poor performance.

func (*Resolvers) SetTimeout

func (r *Resolvers) SetTimeout(d time.Duration)

SetTimeout updates the amount of time this pool will wait for response messages.

func (*Resolvers) Stop

func (r *Resolvers) Stop()

Stop will release resources for the resolver pool and all add resolvers.

func (*Resolvers) WildcardDetected

func (r *Resolvers) WildcardDetected(ctx context.Context, resp *dns.Msg, domain string) bool

WildcardDetected returns true when the provided DNS response could be a wildcard match.

type ThresholdOptions

type ThresholdOptions struct {
	ThresholdValue         uint64
	CumulativeAccumulation bool // instead of continuous
	CountTimeouts          bool
	CountFormatErrors      bool
	CountServerFailures    bool
	CountNotImplemented    bool
	CountQueryRefusals     bool
}