dns NSE Library — Nmap Scripting Engine documentation (original) (raw)

Functions Tables

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

The most common interface to this module are the query andreverse 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, 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😵beef:cafe" local status, result = dns.query('irc.ipv6.efnet.org', {dtype='AAAA'})

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.

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 fieldsfamily - IPv4: "inet" or 1 (default), IPv6: "inet6" or 2mask - byte containing the length of the subnet maskaddress - 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 bynewPacket.

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 2address - string containing the originating subnet IP addressmask - 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.

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, mxRV - 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.