resolvers

README

Fast Use of DNS Resolvers

Designed to support DNS brute-forcing with a minimal number of network connections.

Installation

go get -v -u github.com/caffix/resolvers

Usage

The Resolver type from this package represents a DNS resolver or group of resolvers that support two primary actions: DNS queries and wildcard detection. Requests made to the same Resolver are performed asynchronously at the rate provided to the constructor of queries per second. DNS queries returning responses indicating success can then be checked for wildcards using the built-in detection.

r := resolvers.NewBaseResolver("8.8.8.8", 10, nil)

msg := resolvers.QueryMsg("mail.google.com", 1)
resp, err := r.Query(context.TODO(), msg, resolvers.PriorityNormal, nil)
if err != nil {
    return
}

if r.WildcardType(context.TODO(), resp, "google.com") != resolvers.WildcardTypeNone {
    return
}

Licensing

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

Documentation

Index

• Constants
• Variables
• func ClientSubnetCheck(resolver string) error
• func FirstProperSubdomain(ctx context.Context, r Resolver, name string, priority int) string
• func NsecTraversal(ctx context.Context, r Resolver, domain string, priority int) ([]*dns.NSEC, bool, error)
• func PoolRetryPolicy(times, priority int, msg *dns.Msg) bool
• func QueryMsg(name string, qtype uint16) *dns.Msg
• func RemoveLastDot(name string) string
• func RetryPolicy(times, priority int, msg *dns.Msg) bool
• func ReverseMsg(addr string) *dns.Msg
• func SetupOptions() *dns.OPT
• 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 ResolveError
  • func (e *ResolveError) Error() string
• type Resolver
  • func NewBaseResolver(addr string, perSec int, logger *log.Logger) Resolver
  • func NewResolverPool(resolvers []Resolver, delay time.Duration, baseline Resolver, partnum int, ...) Resolver
• type Retry

Constants

const (
	PriorityLow int = iota
	PriorityNormal
	PriorityHigh
	PriorityCritical
)

The priority levels for Resolver DNS queries.

const (
	AttemptsPriorityLow      int = 50
	AttemptsPriorityNormal   int = 100
	AttemptsPriorityHigh     int = 250
	AttemptsPriorityCritical int = 500
)

The priority levels for Resolver DNS queries.

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

Constants related to DNS labels.

const (
	WildcardTypeNone = iota
	WildcardTypeStatic
	WildcardTypeDynamic
)

Names for the different types of wildcards that can be detected.

const ResolverErrRcode = 100

ResolverErrRcode is our made up rcode to indicate an interface error.

const TimeoutRcode = 101

TimeoutRcode is our made up rcode to indicate that a query timed out.

Variables

var PoolRetryCodes = []int{
	TimeoutRcode,
	ResolverErrRcode,
	dns.RcodeRefused,
	dns.RcodeServerFailure,
	dns.RcodeNotImplemented,
}

PoolRetryCodes are the rcodes that cause the pool to suggest trying again.

var QueryTimeout = 2 * time.Second

QueryTimeout is the duration until a Resolver query expires.

var RetryCodes = []int{
	TimeoutRcode,
	ResolverErrRcode,
}

RetryCodes are the rcodes that cause the resolver to suggest trying again.

Functions

func ClientSubnetCheck

func ClientSubnetCheck(resolver string) error

ClientSubnetCheck ensures that the provided resolver does not send the EDNS client subnet information. The function returns the DNS reply size limit in number of bytes.

func FirstProperSubdomain

func FirstProperSubdomain(ctx context.Context, r Resolver, name string, priority int) 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 NsecTraversal

func NsecTraversal(ctx context.Context, r Resolver, domain string, priority int) ([]*dns.NSEC, bool, error)

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

func PoolRetryPolicy

func PoolRetryPolicy(times, priority int, msg *dns.Msg) bool

PoolRetryPolicy is the default policy used by the resolver pool to determine if a DNS query should be performed again.

func QueryMsg

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

QueryMsg generates a message used for a forward DNS query.

func RemoveLastDot

func RemoveLastDot(name string) string

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

func RetryPolicy

func RetryPolicy(times, priority int, msg *dns.Msg) bool

RetryPolicy is the default policy used to determine if a DNS query should be performed again.

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 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 ResolveError

type ResolveError struct {
	Err   string
	Rcode int
}

ResolveError contains the Rcode returned during the DNS query.

func (*ResolveError) Error

func (e *ResolveError) Error() string

type Resolver

type Resolver interface {
	fmt.Stringer

	// Stop will stop the Resolver.
	Stop()

	// Stopped returns true if the Resolver is already stopped.
	Stopped() bool

	// Query performs a DNS query for the provided name and message type.
	Query(ctx context.Context, msg *dns.Msg, priority int, retry Retry) (*dns.Msg, error)

	// WildcardType returns the DNS wildcard type for the FQDN in the provided message.
	WildcardType(ctx context.Context, msg *dns.Msg, domain string) int
}

Resolver performs DNS resolutions.

func NewBaseResolver

func NewBaseResolver(addr string, perSec int, logger *log.Logger) Resolver

NewBaseResolver initializes a Resolver that sends DNS queries to the provided IP address.

func NewResolverPool

func NewResolverPool(resolvers []Resolver, delay time.Duration, baseline Resolver, partnum int, logger *log.Logger) Resolver

NewResolverPool initializes a ResolverPool that uses the provided Resolvers.

type Retry

type Retry func(times int, priority int, msg *dns.Msg) bool

Retry is the definition for the callbacks used in the Resolver interface.