Library dns

Simple DNS library supporting packet creation, encoding, decoding, and querying.

The most common interface to this module are the query and reverse functions. query performs a DNS query, and reverse prepares an ip address to have a reverse query performed.

query takes two options - a domain name to look up and an optional table of options. For more information on the options table, see the documentation for query.

Example usage: 

 -- After this call, <code>status
is true and result is "72.14.204.104" local status, result = dns.query('www.google.ca')

-- After this call, status is false and result is "No such name" local status, result = dns.query('www.google.abc')

-- After this call, status is true and result is the table {"72.14.204.103", "72.14.204.104", "72.14.204.147", "72.14.204.99"} local status, result = dns.query('www.google.ca', {retAll=true})

-- After this call, status is true and result is the "2001:19f0:0:0:0:dead:beef:cafe" local status, result = dns.query('irc.ipv6.efnet.org', {dtype='AAAA'}) </code>

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/dns.lua

Functions

addClientSubnet (pkt, Z, subnet, client_subnet)

Adds an client-subnet payload to the OPT packet

addNSID (pkt, Z)

Adds an NSID payload to the OPT packet

addOPT (pkt, Z, opt)

Adds an OPT RR to a DNS packet's additional section.

addQuestion (pkt, dname, dtype, class)

Adds a question to a DNS packet table.

addUpdate (pkt, dname, dtype, ttl, data, class)

Adds a update to a DNS packet table

addZone (pkt, dname)

Adds a zone to a DNS packet table

decode (data)

Decodes a DNS packet.

decStr (data, pos)

Decodes a domain in a DNS packet. Handles "compressed" data too.

encode (pkt)

Encode a DNS packet.

findNiceAdditional (dtype, dec, retAll)

Calls the answer fetcher for dtype or returns an error code in case of a "no such name" error.

findNiceAnswer (dtype, dec, retAll)

Calls the answer fetcher for dtype or returns an error code in case of a "no such name" error.

newPacket ()

Creates a new table representing a DNS packet.

query (dname, options)

Query DNS servers for a DNS record.

reverse (ip)

Formats an IP address for reverse lookup.

sendPackets (data, host, port, timeout, cnt, multiple, proto)

Call appropriate protocol handler

update (dname, options)

Adds a record to the Zone

Tables

types

Table of DNS resource types.

Functions

addClientSubnet (pkt, Z, subnet, client_subnet)

Adds an client-subnet payload to the OPT packet

implementing https://tools.ietf.org/html/rfc7871

Parameters

pkt
Table representing DNS packet.
Z
Table of Z flags. Only DO is supported.
subnet
 
client_subnet
table containing the following fields family - IPv4: "inet" or 1 (default), IPv6: "inet6" or 2 mask - byte containing the length of the subnet mask address - string containing the IP address
addNSID (pkt, Z)

Adds an NSID payload to the OPT packet

Parameters

pkt
Table representing DNS packet.
Z
Table of Z flags. Only DO is supported.
addOPT (pkt, Z, opt)

Adds an OPT RR to a DNS packet's additional section.

Only the table of Z flags is supported (i.e., not RDATA). See RFC 2671 section 4.3.

Parameters

pkt
Table representing DNS packet.
Z
Table of Z flags. Only DO is supported.
opt
 
addQuestion (pkt, dname, dtype, class)

Adds a question to a DNS packet table.

Parameters

pkt
Table representing DNS packet.
dname
Domain name to be asked.
dtype
RR to be asked.
class
 
addUpdate (pkt, dname, dtype, ttl, data, class)

Adds a update to a DNS packet table

Parameters

pkt
Table representing DNS packet.
dname
Domain name to be asked.
dtype
to be updated
ttl
the time-to-live of the record
data
type specific data
class
 
addZone (pkt, dname)

Adds a zone to a DNS packet table

Parameters

pkt
Table representing DNS packet.
dname
Domain name to be asked.
decode (data)

Decodes a DNS packet.

Parameters

data
Encoded DNS packet.

Return value:

Table representing DNS packet.
decStr (data, pos)

Decodes a domain in a DNS packet. Handles "compressed" data too.

Parameters

data
Complete DNS packet.
pos
Starting position in packet.

Return values:

  1. Position after decoding.
  2. Decoded domain, or nil on error.
encode (pkt)

Encode a DNS packet.

Caution: doesn't encode answer and authority part.

Parameters

pkt
Table representing DNS packet, initialized by newPacket.

Return value:

Encoded DNS packet.
findNiceAdditional (dtype, dec, retAll)

Calls the answer fetcher for dtype or returns an error code in case of a "no such name" error.

Parameters

dtype
DNS resource record type.
dec
Decoded DNS response.
retAll
If true, return all entries, not just the first.

Return values:

  1. True if one or more answers of the required type were found - otherwise false.
  2. Answer according to the answer fetcher for dtype or an Error message.
findNiceAnswer (dtype, dec, retAll)

Calls the answer fetcher for dtype or returns an error code in case of a "no such name" error.

Parameters

dtype
DNS resource record type.
dec
Decoded DNS response.
retAll
If true, return all entries, not just the first.

Return values:

  1. True if one or more answers of the required type were found - otherwise false.
  2. Answer according to the answer fetcher for dtype or an Error message.
newPacket ()

Creates a new table representing a DNS packet.

Return value:

Table representing a DNS packet.
query (dname, options)

Query DNS servers for a DNS record.

Parameters

dname
Desired domain name entry.
options
A table containing any of the following fields:
  • dtype: Desired DNS record type (default: "A").
  • host: DNS server to be queried (default: DNS servers known to Nmap).
  • port: Port of DNS server to connect to (default: 53).
  • tries: How often should query try to contact another server (for non-recursive queries).
  • retAll: Return all answers, not just the first.
  • retPkt: Return the packet instead of using the answer-fetching mechanism.
  • norecurse: If true, do not set the recursion (RD) flag.
  • noauth: If true, do not try to find authoritative server
  • multiple: If true, expects multiple hosts to respond to multicast request
  • flags: numeric value to set flags in the DNS query to a specific value
  • id: numeric value to use for the DNS transaction id
  • nsid: If true, queries the server for the nameserver identifier (RFC 5001)
  • subnet: table, if set perform a edns-client-subnet lookup. The table should contain the fields: family - IPv4: "inet" or 1 (default), IPv6: "inet6" or 2 address - string containing the originating subnet IP address mask - number containing the number of subnet bits

Return values:

  1. true if a dns response was received and contained an answer of the requested type, or the decoded dns response was requested (retPkt) and is being returned - or false otherwise.
  2. String answer of the requested type, table of answers or a String error message of one of the following: "No Such Name", "No Servers", "No Answers", "Unable to handle response"
reverse (ip)

Formats an IP address for reverse lookup.

Parameters

ip
IP address string.

Return value:

"Domain"-style representation of IP as subdomain of in-addr.arpa or ip6.arpa.
sendPackets (data, host, port, timeout, cnt, multiple, proto)

Call appropriate protocol handler

Parameters

data
Data to be sent.
host
Host to connect to.
port
Port to connect to.
timeout
Number of ms to wait for a response.
cnt
Number of tries.
multiple
If true, keep reading multiple responses until timeout (ignored for TCP)
proto
 

Return values:

  1. Status (true or false).
  2. Response (if status is true).
update (dname, options)

Adds a record to the Zone

Parameters

dname
containing the hostname to add
options
A table containing any of the following fields:
  • dtype: Desired DNS record type (default: "A").
  • host: DNS server to be queried (default: DNS servers known to Nmap).
  • timeout: The time to wait for a response
  • sendCount: The number of send attempts to perform
  • zone: If not supplied deduced from hostname
  • data: Table or string containing update data (depending on record type): - String containing the IP address NAME - String containing the FQDN X - Table containing pref, mx RV - Table containing prio, weight, port, target

Return values:

  1. status true on success false on failure
  2. msg containing the error message Examples Adding different types of records to a server * update( "www.cqure.net", { host=host, port=port, dtype="A", data="10.10.10.10" } ) * update( "alias.cqure.net", { host=host, port=port, dtype="CNAME", data="www.cqure.net" } ) * update( "cqure.net", { host=host, port=port, dtype="MX", data={ pref=10, mx="mail.cqure.net"} }) * update( "_ldap._tcp.cqure.net", { host=host, port=port, dtype="SRV", data={ prio=0, weight=100, port=389, target="ldap.cqure.net" } } ) Removing the above records by setting an empty data and a ttl of zero * update( "www.cqure.net", { host=host, port=port, dtype="A", data="", ttl=0 } ) * update( "alias.cqure.net", { host=host, port=port, dtype="CNAME", data="", ttl=0 } ) * update( "cqure.net", { host=host, port=port, dtype="MX", data="", ttl=0 } ) * update( "_ldap._tcp.cqure.net", { host=host, port=port, dtype="SRV", data="", ttl=0 } )

Tables

types

Table of DNS resource types.