dnszilla

README

dnsmonster's trusty sidekick

NOTE: this is a work in progress and is not ready for production use. It should be ready for testing and experimentation.

read the docs here

Documentation

Overview

dnszilla follows the same model of work as dnsmonster.

components

1. it has a set of inputs that can be deliverd via:

• stdin
• a kafka topic

2. it has a set of processors that take the inputs and apply a logic to them, then depending on the logic, will provide an alarm feed currently supported processors are:

• base64: alarms on DNS questions that are base64 encoded
• beaconing: alarms on DNS questions that are periodic and have a specific pattern
• csv_cidr: alarms on DNS servers and A answers that are in a list of CIDR ranges
• csv_fqdn: alarms on DNS questions (full match, prefix or suffix) that are in a list of FQDNs
• mixedcase: alarms on DNS questions that are mixed case
• multiquestion: alarms on DNS packets that have more than one question in them
• rate: alarms on source IPs that are sending DNS message at a rate higher than a threshold
• rebinding: alarms on DNS responses that are in RFC1918 space
• warninglist_cidr: alarms on DNS questtions or answers that have an IP in a list of CIDR ranges based on MISP warning lists
• warninglist_fqdn: alarms on DNS questions that are in a list of FQDNs based on MISP warning lists

3. a set of alarm providers that consume from a processor and deliver the alarms to a set of outputs currently supported alarm provider(s) are:

• stdout

Use dnszilla as a binary

• download dnszilla binary from the releases page

• use config.yaml.example as a template to create your own config.yaml and set up inputs, processors and outputs. note that all components of dnszilla are named and the names are used to reference component relationships in the config file. for example, if you want to use the base64 processor, you need to add it to the processors section of the config file and then reference it in the alarm_providers section of the config file. if the name is not provided, the component name itself will be used as the name.

• run dnszilla with the config file as an argument

  dnszilla -c config.yaml

Index

• func GetAnswers(msg dns.Msg) []net.IP
• func UnmarshalDNS(rawBytes []byte) (msg dns.Msg)
• type DNSResult
• type DNSResultBinary

Functions

func GetAnswers

func GetAnswers(msg dns.Msg) []net.IP

GetAnswers returns a slice of IPs that are included in the response section of a DNS message.

func UnmarshalDNS

func UnmarshalDNS(rawBytes []byte) (msg dns.Msg)

Types

type DNSResult

type DNSResult struct {
	Timestamp    time.Time
	DNS          dns.Msg
	IPVersion    uint8
	SrcIP        net.IP
	SrcPort      uint16 `json:",omitempty"`
	DstIP        net.IP
	DstPort      uint16 `json:",omitempty"`
	Protocol     string
	PacketLength uint16
	Identity     string `json:",omitempty"`
	Version      string `json:",omitempty"`
}

DNSResult struct is built using dnsmonster's JSONL output schema as mentioned here, the JSON-marshalled output of miekg/dns can not be unmarshalled back as-is, since the interfaces providing different types of RR do not impelment the `json.Unmarshaler` interface. the DNSResultBinary struct is sent over the wire in GOB format which solves this problem entirely.

type DNSResultBinary

type DNSResultBinary struct {
	Timestamp    time.Time
	DNS          json.RawMessage //packed version of dns.msg (dns.Msg.Pack())
	IPVersion    uint8
	SrcIP        net.IP
	SrcPort      uint16 `json:",omitempty"`
	DstIP        net.IP
	DstPort      uint16 `json:",omitempty"`
	Protocol     string
	PacketLength uint16
	Identity     string `json:",omitempty"`
	Version      string `json:",omitempty"`
}

DNSResultBinary ships the packed version of dns.Msg over the wire rather than a JSON representation of the dns.Msg. This is done to avoid the problem of unmarshalling the JSON representation of dns.Msg back to dns.Msg.