Reassemble DNS Messages from PCAP

reassembledns extracts DNS messages from *.pcap files and writes them to a binary *.dns file. IP fragments and DNS-over-TCP connections are reassembled into whole DNS messages for easy analysis of network traces.

Features

• Supports IPv4/IPv6 networks and UDP/TCP transports.
• Supports huge input *.pcap files by processing them progressively. reassembledns does not load the whole network trace into memory.
• IP fragments and TCP streams are reassembled, thus giving you a consistent stream of whole DNS messages. Each message is timestamped with the point when the complete message had been received.
• Multiple *.pcap files can be passed as input and will be combined into a single *.dns output file. This is useful if *.pcap files have been rotated (tcpdump options -C or -G).

TCP Reassembly

DNS-over-TCP allows the transport of multiple DNS messages over one TCP connection. RFC 1035 specifies a protocol, which prepends each DNS message with its length. Unlike with UDP, DNS messages are not aligned to the underlying TCP segments. One data segment may contain part of a DNS message or more than one DNS message. reassembledns hides this complexity and returns whole DNS messages.

TCP connections are processed as unidirectional TCP streams. Each TCP stream starts with a SYN or SYN/ACK segment and is concluded by a FIN or RST segment, but only if the sequence numbers match. Idle connections are force-closed after a 10 minutes timeout to avoid state bloat when parsing huge files. Duplicate or out-of-order data is handled in accordance with TCP sequence number arithmetic (RFC 793). Retransmitted data does not need to be aligned to the same segment sizes, i.e., partly overlapping segments are handled appropriately.

Usage

# Reassemble PCAP input into DNS output
python3 -m reassembledns.pcap input.pcap output.dns
# Parse DNS file
python3 -m reassembledns.parser output.dns

Custom analysis scripts can import reassembledns.parser and use the following functions to iterate over DNS messages:

• file_parser(filenames_list): iterates over *.dns files and yields the following tuple per message:
  • msgbuf: DNS message as raw bytes.
  • ts: unixtime of message received as int.
  • frameno: reference to frame number in *.pcap file (not a continous number if multiple *.pcap files have been combined).
  • ipver: IP version 4 or 6 as int.
  • ip_src, ip_dst: source and destination IP address as str.
  • transport_type: 6 (TCP) or 17 (UDP) as int.
  • sport, dport: source and destination port number as int.
• dns_parser(filenames_list): similar to file_parser(), but yields the following tuple per message:
  • dnsmsg: DNS message parsed as dns.message.Message.
  • msglen: length of raw DNS message as int.
  • ts, frameno, ipver, ip_src, ip_dst, transport_type, sport, dport: same as above.

The *.dns file format is documented in dns_file_format.txt.

Installation

Prerequisites

• Python 3
• dpkt
• dnspython (only for reassembledns.parser)

Download

• reassembledns-0.2.tar.gz

Old version for Python 2.7: reassemble_dns.tar.gz