dns

README

UDP

Parsing

1. Attempt to decode each UDP packet.
2. If it succeeds, a transaction is sent.

Error management

• Debug information is printed if:

  • A packet fails to decode.

• Error Notes are published if:

  • Never

TCP

Parsing

1. Fetch the first two bytes of a message containing the length of the message (RFC 1035).
2. Fill the buffer DnsStream.rawData with each new Parse.
3. Once the buffer has the expected length (first two bytes), it is decoded and the message is published.

Error management

• Debug information is printed if:

  • A message has an unexpected length at any point of the transmission (Parse, GapInStream, ReceivedFin).
  • A message fails to decode.

• Error Notes are published if:

  • A response following a request (dnsConnectionData.prevRequest) fails to decode.
  • A response following a request (dnsConnectionData.prevRequest) has an unexpected length at any point of the transmission (Parse, GapInStream, ReceivedFin).

When response error Notes are linked to the previous request, the transaction is then published and removed from the cache (see publishResponseError()).

TODO

General

• Publish an event with Notes when a Query or a lone Response cannot be decoded.
• Consider adding ICMP support to
  • correlate ICMP type 3, code 4 (datagram too big) with DNS messages,
  • correlate ICMP type 3, code 13 (administratively prohibited) or ICMP type 3, code 3 (port unreachable) with blocked DNS messages.

Documentation

Overview

Package dns provides support for parsing DNS messages and reporting the results. This package supports the DNS protocol as defined by RFC 1034 and RFC 1035. It does not have any special support for RFC 2671 (EDNS) or RFC 4035 (DNS Security Extensions), but since those specifications only add backwards compatible features there will be no issues handling the messages.

Index

• func New(testMode bool, results protos.Reporter, cfg *common.Config) (protos.Plugin, error)
• type Answer
• type BytesEncoder
  • func (b BytesEncoder) Encode() ([]byte, error)
  • func (b BytesEncoder) Length() int
• type DNS
• type Flags
• type KafkaConfig
• type MapStrWrapper
  • func (m *MapStrWrapper) Encode() ([]byte, error)
  • func (m *MapStrWrapper) Length() int
• type MetaConfig
• type MetaRetryConfig
• type Opt
• type Question
• type Record
• type RecordEncoder
  • func (re *RecordEncoder) Encode() ([]byte, error)
  • func (re *RecordEncoder) Length() int

Functions

func New

func New(
	testMode bool,
	results protos.Reporter,
	cfg *common.Config,
) (protos.Plugin, error)

Types

type Answer

type Answer struct {
	Class string `json:"class, omitempty"`
	Data  string `json:"data, omitempty"`
	Name  string `json:"name, omitempty"`
	TTL   string `json:"ttl, omitempty"`
	Type  string `json:"type, omitempty"`

	Flags     string `json:"flags, omitempty"`
	Protocol  string `json:"protocol, omitempty"`
	Algorithm string `json:"algorithm, omitempty"`

	KeyTag     string `json:"key_tag, omitempty"`
	DigestType string `json:"digest_type, omitempty"`

	Preference uint16 `json:"preference, omitempty"`
	TypeBits   string `json:"type_bits, omitempty"`
	Hash       string `json:"hash, omitempty"`
	Iterations string `json:"iterations, omitempty"`
	Salt       string `json:"salt, omitempty"`

	TypeCovered string `json:"type_covered, omitempty"`
	Labels      string `json:"labels, omitempty"`
	OriginalTTL string `json:"original_ttl, omitempty"`

	Expiration string `json:"expiration, omitempty"`
	Inception  string `json:"inception, omitempty"`
	SignerName string `json:"signer_name, omitempty"`

	Rname   string `json:"rname, omitempty"`
	Serial  uint32 `json:"serial, omitempty"`
	Refresh uint32 `json:"refresh, omitempty"`
	Retry   uint32 `json:"retry, omitempty"`
	Expire  uint32 `json:"expire, omitempty"`
	Minimum uint32 `json:"minimum, omitempty"`

	Priority uint16 `json:"priority, omitempty"`
	Weight   uint16 `json:"weight, omitempty"`
	Port     uint16 `json:"port, omitempty"`
}

type BytesEncoder

type BytesEncoder []byte

func (BytesEncoder) Encode

func (b BytesEncoder) Encode() ([]byte, error)

func (BytesEncoder) Length

func (b BytesEncoder) Length() int

type DNS

type DNS struct {
	ID               uint16    `json:"id, omitempty"`
	OpCode           string    `json:"op_code, omitempty"`
	Flags            *Flags    `json:"flags, omitempty"`
	ResponseCode     string    `json:"response_code, omitempty"`
	Question         *Question `json:"question, omitempty"`
	Opt              *Opt      `json:"opt, omitempty"`
	AnswersCount     int       `json:"answers_count, omitempty"`
	AuthoritiesCount int       `json:"authorities_count, omitempty"`
	AdditionalsCount int       `json:"additionals_count, omitempty"`
	Answers          []*Answer `json:"answers, omitempty"`
	Authorities      []*Answer `json:"authorities, omitempty"`
	Additionals      []*Answer `json:"additionals, omitempty"`
}

type Flags

type Flags struct {
	AuthenticData      bool `json:"authentic_data, omitempty"`
	Authoritative      bool `json:"authoritative, omitempty"`
	CheckingDisabled   bool `json:"checking_disabled, omitempty"`
	RecursionAvailable bool `json:"recursion_available, omitempty"`
	RecursionDesired   bool `json:"recursion_desired, omitempty"`
	TruncatedResponse  bool `json:"truncated_response, omitempty"`
}

type KafkaConfig

type KafkaConfig struct {
	Hosts []string `config:"hosts"               validate:"required"`
	Topic string   `config:"topic"               validate:"required"`
	// TLS              *tlscommon.Config         `config:"ssl"`
	Timeout time.Duration `config:"timeout"             validate:"min=1"`
	// Metadata         MetaConfig                `config:"metadata"`
	// Key              *fmtstr.EventFormatString `config:"key"`
	// Partition        map[string]*common.Config `config:"partition"`
	KeepAlive            time.Duration `config:"keep_alive"          validate:"min=0"`
	RequiredACKs         *int          `config:"required_acks"       validate:"min=-1"`
	BrokerTimeout        time.Duration `config:"broker_timeout"      validate:"min=1"`
	Compression          string        `config:"compression"`
	CompressionLevel     int           `config:"compression_level"`
	Version              kafka.Version `config:"version"`
	BulkMaxSize          int           `config:"bulk_max_size"`
	MaxRetries           int           `config:"max_retries"         validate:"min=0"`
	RetryBackoffDuration time.Duration `config:"retry_backoff_duration"`
	ClientID             string        `config:"client_id"`
	ChanBufferSize       int           `config:"channel_buffer_size" validate:"min=1"`
	Username             string        `config:"username"`
	Password             string        `config:"password"`
	// Codec            codec.Config              `config:"codec"`
	FlushFrequency  time.Duration `config:"flush_frequency"`
	FlushMaxBytes   int           `config:"flush_max_bytes"`
	MaxMessageBytes int           `config:"max_message_bytes"   validate:"min=1"`
	MaxMessages     int           `config:"max_messages"   validate:"min=1"`
	Messages        int           `config:"messages"   validate:"min=1"`
}

type MapStrWrapper

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

func (*MapStrWrapper) Encode

func (m *MapStrWrapper) Encode() ([]byte, error)

func (*MapStrWrapper) Length

func (m *MapStrWrapper) Length() int

type MetaConfig

type MetaConfig struct {
	Retry       MetaRetryConfig `config:"retry"`
	RefreshFreq time.Duration   `config:"refresh_frequency" validate:"min=0"`
}

type MetaRetryConfig

type MetaRetryConfig struct {
	Max     int           `config:"max"     validate:"min=0"`
	Backoff time.Duration `config:"backoff" validate:"min=0"`
}

type Opt

type Opt struct {
	Do       bool   `json:"do, omitempty"`
	ExtRcode string `json:"ext_rcode, omitempty"`
	UDPSize  uint16 `json:"udp_size, omitempty"`
	Version  string `json:"version, omitempty"`
	DAU      string `json:"dau, omitempty"`
	DHU      string `json:"dhu, omitempty"`
	LOCAL    string `json:"local, omitempty"`
	LLQ      string `json:"llq, omitempty"`
	N3U      string `json:"n3u, omitempty"`
	NSID     string `json:"nsid, omitempty"`
	SUBNET   string `json:"subnet, omitempty"`
	COOKIE   string `json:"cookie, omitempty"`
	UL       string `json:"ul, omitempty"`
}

type Question

type Question struct {
	Class       string `json:"class, omitempty"`
	EtldPlusOne string `json:"etld_plus_one, omitempty"`
	Name        string `json:"name, omitempty"`
	Type        string `json:"type, omitempty"`
}

type Record

type Record struct {
	Timestamp    string           `json:"timestamp"`
	Type         string           `json:"type, omitempty"`
	Transport    string           `json:"transport, omitempty"`
	Status       string           `json:"status, omitempty"`
	Notes        string           `json:"notes, omitempty"`
	BytesIn      int              `json:"bytes_in, omitempty"`
	BytesOut     int              `json:"bytes_out, omitempty"`
	ResponseTime float64          `json:"response_time, omitempty"`
	Method       string           `json:"method, omitempty"`
	Query        string           `json:"query, omitempty"`
	Resource     string           `json:"resource, omitempty"`
	Src          *common.Endpoint `json:"src, omitempty"`
	Dst          *common.Endpoint `json:"dst, omitempty"`
	DNS          *DNS             `json:"dns, omitempty"`
}

type RecordEncoder

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

func (*RecordEncoder) Encode

func (re *RecordEncoder) Encode() ([]byte, error)

func (*RecordEncoder) Length

func (re *RecordEncoder) Length() int