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.
• Add EDNS and DNSSEC support (consider using miekg/dns instead of gopacket).
• 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

This file contains the name mapping data used to convert various DNS IDs to their string values.

Index

• Constants
• Variables
• func New(testMode bool, results publish.Transactions, cfg *ucfg.Config) (protos.Plugin, error)
• type DNSError
  • func (e *DNSError) Error() string
  • func (e *DNSError) ResponseError() string
• type Dns
  • func (dns *Dns) ConnectionTimeout() time.Duration
  • func (dns *Dns) GapInStream(tcpTuple *common.TcpTuple, dir uint8, nbytes int, private protos.ProtocolData) (priv protos.ProtocolData, drop bool)
  • func (dns *Dns) GetPorts() []int
  • func (dns *Dns) Parse(pkt *protos.Packet, tcpTuple *common.TcpTuple, dir uint8, ...) protos.ProtocolData
  • func (dns *Dns) ParseUdp(pkt *protos.Packet)
  • func (dns *Dns) ReceivedFin(tcpTuple *common.TcpTuple, dir uint8, private protos.ProtocolData) protos.ProtocolData
• type DnsMessage
• type DnsStream
  • func (stream *DnsStream) PrepareForNewMessage()
• type DnsTransaction
• type DnsTuple
  • func DnsTupleFromIpPort(t *common.IpPortTuple, trans Transport, id uint16) DnsTuple
  • func (t *DnsTuple) ComputeHashebles()
  • func (t *DnsTuple) Hashable() HashableDnsTuple
  • func (t *DnsTuple) RevHashable() HashableDnsTuple
  • func (t DnsTuple) Reverse() DnsTuple
  • func (t *DnsTuple) String() string
• type Error
• type HashableDnsTuple
• type Transport
  • func (t Transport) String() string

Constants

const (
	Query    = false
	Response = true
)

Constants used to associate the DNS QR flag with a meaningful value.

const (
	TransportTcp = iota
	TransportUdp
)

const DecodeOffset = 2

RFC 1035 The 2 first bytes contain the length of the message

const MaxDnsMessageSize = (1 << 16) - 1

const MaxDnsTupleRawSize = 16 + 16 + 2 + 2 + 4 + 1

Variables

var (
	NonDnsMsg           = &DNSError{Err: "Message's data could not be decoded as DNS"}
	ZeroLengthMsg       = &DNSError{Err: "Message's length was set to zero"}
	UnexpectedLengthMsg = &DNSError{Err: "Unexpected message data length"}
	DuplicateQueryMsg   = &DNSError{Err: "Another query with the same DNS ID from this client " +
		"was received so this query was closed without receiving a response"}
	IncompleteMsg = &DNSError{Err: "Message's data is incomplete"}
	NoResponse    = &DNSError{Err: "No response to this query was received"}
)

Messages

var (
	OrphanedResponse = &DNSError{Err: "Response: received without an associated Query"}
)

TCP responses

var TransportNames = []string{
	"tcp",
	"udp",
}

Functions

func New

func New(
	testMode bool,
	results publish.Transactions,
	cfg *ucfg.Config,
) (protos.Plugin, error)

Types

type DNSError

type DNSError struct {
	Err string
}

func (*DNSError) Error

func (e *DNSError) Error() string

func (*DNSError) ResponseError

func (e *DNSError) ResponseError() string

type Dns

type Dns struct {
	// Configuration data.
	Ports               []int
	Send_request        bool
	Send_response       bool
	Include_authorities bool
	Include_additionals bool
	// contains filtered or unexported fields
}

func (*Dns) ConnectionTimeout

func (dns *Dns) ConnectionTimeout() time.Duration

func (*Dns) GapInStream

func (dns *Dns) GapInStream(tcpTuple *common.TcpTuple, dir uint8, nbytes int, private protos.ProtocolData) (priv protos.ProtocolData, drop bool)

func (*Dns) GetPorts

func (dns *Dns) GetPorts() []int

func (*Dns) Parse

func (dns *Dns) Parse(pkt *protos.Packet, tcpTuple *common.TcpTuple, dir uint8, private protos.ProtocolData) protos.ProtocolData

func (*Dns) ParseUdp

func (dns *Dns) ParseUdp(pkt *protos.Packet)

func (*Dns) ReceivedFin

func (dns *Dns) ReceivedFin(tcpTuple *common.TcpTuple, dir uint8, private protos.ProtocolData) protos.ProtocolData

type DnsMessage

type DnsMessage struct {
	Ts           time.Time          // Time when the message was received.
	Tuple        common.IpPortTuple // Source and destination addresses of packet.
	CmdlineTuple *common.CmdlineTuple
	Data         *mkdns.Msg // Parsed DNS packet data.
	Length       int        // Length of the DNS message in bytes (without DecodeOffset).
}

DnsMessage contains a single DNS message.

type DnsStream

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

DnsStream contains DNS data from one side of a TCP transmission. A pair of DnsStream's are used to represent the full conversation.

func (*DnsStream) PrepareForNewMessage

func (stream *DnsStream) PrepareForNewMessage()

type DnsTransaction

type DnsTransaction struct {
	ResponseTime int32 // Elapsed time in milliseconds between the request and response.
	Src          common.Endpoint
	Dst          common.Endpoint
	Transport    Transport
	Notes        []string

	Request  *DnsMessage
	Response *DnsMessage
	// contains filtered or unexported fields
}

type DnsTuple

type DnsTuple struct {
	Ip_length          int
	Src_ip, Dst_ip     net.IP
	Src_port, Dst_port uint16
	Transport          Transport
	Id                 uint16
	// contains filtered or unexported fields
}

DnsTuple contains source IP/port, destination IP/port, transport protocol, and DNS ID.

func DnsTupleFromIpPort

func DnsTupleFromIpPort(t *common.IpPortTuple, trans Transport, id uint16) DnsTuple

func (*DnsTuple) ComputeHashebles

func (t *DnsTuple) ComputeHashebles()

func (*DnsTuple) Hashable

func (t *DnsTuple) Hashable() HashableDnsTuple

Hashable returns a hashable value that uniquely identifies the DNS tuple.

func (*DnsTuple) RevHashable

func (t *DnsTuple) RevHashable() HashableDnsTuple

Hashable returns a hashable value that uniquely identifies the DNS tuple after swapping the source and destination.

func (DnsTuple) Reverse

func (t DnsTuple) Reverse() DnsTuple

func (*DnsTuple) String

func (t *DnsTuple) String() string

type Error

type Error interface {
	error
	ResponseError() string
}

type HashableDnsTuple

type HashableDnsTuple [MaxDnsTupleRawSize]byte

type Transport

type Transport uint8

Transport protocol.

func (Transport) String

func (t Transport) String() string