PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2025-12-17 13:09:02 +00:00
Code Issues Projects Releases Wiki Activity

Reformat and merge documentation for some NSE modules: comm, datafiles, dns,

Browse Source 
http, ipOps, listop, and match. This is mainly merging the best documentation
from the module source and scripting.xml into the module, with the aim of
making the source code the canonical source for module documentation.
This commit is contained in:
david
2008-10-15 22:03:14 +00:00
parent 4b17b36913
commit 12e34eb5b0
8 changed files with 237 additions and 677 deletions
Download Patch File Download Diff File Expand all files Collapse all files

442
docs/scripting.xml
View File

@@ -1428,53 +1428,6 @@ if(s) code_to_be_done_on_match end
<indexterm class="endofrange" startref="nse-openssl-indexterm"/>
</sect2>
<sect2 id="nse-lib-ipOps">
<title>IP Operations</title>
<indexterm><primary><varname>ipOps</varname> NSE module</primary></indexterm>
<para>
The <literal>ipOps</literal> module provides some functions for
manipulating IPv4 addresses. The functions reside inside the
<literal>ipOps</literal> namespace.
</para>
<variablelist>
<varlistentry>
<term>
<indexterm><primary>private addresses</primary><secondary>in NSE</secondary></indexterm>
<option>bool = ipOps.isPrivate("ip-string")</option>
</term>
<listitem>
<para>
checks whether an IP address, provided as a string in
dotted-quad notation, is part of the non-routed private IP address
space, as described in <ulink role="hidepdf" url="http://www.rfc-editor.org/rfc/rfc1918.txt">RFC 1918</ulink>. These addresses are the well-known
<literal>10.0.0.0/8</literal>, <literal>192.168.0.0/16</literal> and
<literal>172.16.0.0/12</literal> networks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>DWORD = ipOps.todword("ip-string")</option>
</term>
<listitem>
<para>
returns the IP address as DWORD value (i.e. the IP <replaceable>a.b.c.d</replaceable> becomes
<literal>(((a*256+b)*256+c)*256+d)</literal> )
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>a,b,c,d = ipOps.get_parts_as_number("ip-string")</option>
</term>
<listitem>
<para>
returns 4 numbers corresponding to the fields in dotted-quad notation.
For example, <literal>ipOps.get_parts_as_number("192.168.1.1")
</literal> returns <literal>192,168,1,1</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-shortport">
<title>Short Portrules</title>
<indexterm><primary><varname>shortport</varname> NSE module</primary></indexterm>
@@ -1527,159 +1480,6 @@ if(s) code_to_be_done_on_match end
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-listop">
<title>Functional Programming Style List Operations</title>
<indexterm><primary><varname>listop</varname> NSE module</primary></indexterm>
<para>
People used to programming in functional languages, such as Lisp or
Haskell, appreciate their handling of lists very much. The <literal>listop</literal> module tries to bring much of the functionality from
functional languages to Lua using Lua's central data structure, the table,
as a base for its list operations. Highlights include a <literal>map</literal>
function applying a given function to each element of a list.
</para>
<variablelist>
<varlistentry>
<term><option>bool = listop.is_empty(list)</option>
</term>
<listitem>
<para>
Returns <literal>true</literal> if the given list is empty.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>bool = listop.is_list(value)</option>
</term>
<listitem>
<para>
Returns <literal>true</literal> if the given value is a list (or rather a table).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.map(function, list)</option>
</term>
<listitem>
<para>
The provided function is applied to each element of the list
separately. The returned list contains the results of each
function call. For example <literal>listop.map(tostring,{1,2,true})
</literal> returns <literal>{"1","2","true"}</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>value = listop.apply(function, list)</option>
</term>
<listitem>
<para>
All of the elements in the list are passed to a call of <literal>
function</literal>. The result is then returned. For example
<literal>listop.apply(math.max,{1,5,6,7,50000})</literal>
yields <literal>50000</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.filter(predicate, list)</option>
</term>
<listitem>
<para>
Returns a list containing only those elements for which the predicate
returns true. The predicate has to be a function, which takes an
element of the list as argument and the result of which
is interpreted as a Boolean value. If it returns true (or rather
anything besides <literal>false</literal> and <literal>nil</literal>)
the argument is appended to the return value of <literal>filter</literal>.
For example: <literal>listop.filter(isnumber,{1,2,3,"foo",4,"bar"})</literal> returns
<literal>{1,2,3,4}</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.flatten(list)</option>
</term>
<listitem>
<para>
Since a list can itself contain lists as elements,
<literal>flatten</literal> returns a list which
only contains values that are not themselves
lists. For example:
<literal>listop.flatten({1,2,3,"foo",{4,5,{"bar"}}})</literal> returns
<literal>{1,2,3,"foo",4,5,"bar"}</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.append(list1, list2)</option>
</term>
<listitem>
<para>
Returns a list containing all elements of list1 appended by all
elements of <replaceable>list2</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.cons(value1, value2)</option>
</term>
<listitem>
<para>
Returns a list containing <replaceable>value1</replaceable> appended by <replaceable>value2</replaceable>, which may be
of any type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list = listop.reverse(list)</option>
</term>
<listitem>
<para>
Returns a list containing all elements of the given list in inverted
order.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>value = listop.car(list)</option>
</term>
<listitem>
<para>
Returns the first element of the given list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>value = listop.ncar(list,n)</option>
</term>
<listitem>
<para>
Returns the nth (or first if n is omitted) element of the given list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>value = listop.cdr(list)</option>
</term>
<listitem>
<para>
Returns a list containing all elements but the first of the
given list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>value = listop.ncdr(list, n)</option>
</term>
<listitem>
<para>
Returns a list containing all elements but the first n of the
given list, where n is 2 if it is omitted.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-strbuf">
<title>String Buffer Operations</title>
<indexterm><primary><varname>strbuf</varname> NSE module</primary></indexterm>
@@ -1802,185 +1602,6 @@ if(s) code_to_be_done_on_match end
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-match">
<title>Buffered Network I/O Helper Functions</title>
<indexterm><primary><varname>match</varname> NSE module</primary></indexterm>
<para>
The <literal>match</literal> module was written to provide
functions which can be used for delimiting data received by the
<literal>receive_buf()</literal> function from the Network I/O API:
</para>
<variablelist>
<varlistentry>
<term><option>start,end = match.regex("regexpattern")</option>
</term>
<listitem>
<para>
This is actually a wrapper around NSE's PCRE library <literal>exec</literal> function (see <xref linkend="nse-pcre"/>), thus
giving script developers the possibility to use regular expressions
for delimiting instead of Lua's string patterns. If you want to get
the data in chunks separated by <literal>pattern</literal> (which has to be a valid
regular expression), you would write <literal>status, val =
sockobj:receive_buf(match.regex("pattern"))</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>start,end = match.numbytes(number)</option>
</term>
<listitem>
<para>
Takes a number as its argument and returns that
many bytes. It can be used to get a buffered
version of
<literal>sockobj:receive_bytes(n)</literal> in
case a script requires more than one
fixed-size chunk, as the unbuffered version
may return more bytes than requested and thus
would require you to do the parsing on your
own.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-http">
<title>HTTP Functions</title>
<indexterm><primary><varname>http</varname> NSE module</primary></indexterm>
<para>
The <literal>http</literal> module provides functions for dealing with the client side of the http protocol.
The functions reside inside the <literal>http</literal> namespace.
The return value of each function in this module is a table with the following keys:
<literal>status</literal>, <literal>status-line</literal>, <literal>header</literal>
and <literal>body</literal>.
<literal>status</literal> is a number representing the HTTP
status code returned in response to the HTTP request. In case
of an unhandled error, <literal>status</literal>
is <literal>nil</literal>. <literal>status-line</literal> is
the entire status message which includes the HTTP version,
status code and reason phrase. The <literal>header</literal>
value is a table containing key-value pairs of HTTP headers
received in response to the request. The header names are in
lower-case and are the keys to their corresponding header
values (e.g. <literal>header.location =
"http://nmap.org/"</literal>). Multiple headers of the same
name are concatenated and separated by
commas. The <literal>body</literal> value is a string
containing the body of the HTTP response.</para>
<variablelist>
<varlistentry>
<term><option>table = http.get(host,port,path,[options])</option>
</term>
<listitem>
<para>
Fetches a resource with a <literal>GET</literal> request.
The first argument is either a string with the hostname or a
table like the host table passed by nmap. The second argument
is either the port number or a table like the port table passed
by nmap. The third argument is the path of the resource. The fourth
argument is a table for further options. The table may have 2 keys:
<literal>timeout</literal> and <literal>header</literal>.
<literal>timeout</literal> is the timeout used for the socket
operations. <literal>header</literal> is a table with additional
headers to be used for the request.
The function builds the request and calls <literal>http.request</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>table = http.request(host,port,request,[options])</option>
</term>
<listitem>
<para>
Sends <literal>request</literal> to <literal>host</literal>:<literal>port</literal>
and parses the answer.
The first argument is either a string with the hostname or a
table like the host table passed by nmap. The second argument
is either the port number or a table like the port table passed
by nmap. SSL is used for the request if either <literal>port.service</literal>
equals <literal>https</literal> or <literal>port.version.service_tunnel</literal>
equals <literal>ssl</literal>. The third argument is the request. The fourth
argument is a table for further options. You can specify a timeout
for the socket operations with the timeout key.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>table = http.get_url(url,[options])</option>
</term>
<listitem>
<para>
Parses <literal>url</literal> and calls <literal>http.get</literal>
with the result.
The second argument is a table for further options. The table may have 2 keys:
<literal>timeout</literal> and <literal>header</literal>.
<literal>timeout</literal> is the timeout used for the socket
operations. <literal>header</literal> is a table with additional
headers to be used for the request.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-comm">
<title>Common Communication Functions</title>
<indexterm><primary><varname>comm</varname> NSE module</primary></indexterm>
<para>
The <literal>comm</literal> module provides functions for common network discovery
tasks such as banner-grabbing and making a quick exchange of data. These functions'
return values are setup for use with exception handling via <literal>nmap.new_try()</literal>.
<indexterm><primary>exceptions in NSE</primary></indexterm>
</para>
<para>
These functions can all be passed a table of options, but it's not required.
The relevant indexes for this table are <literal>bytes</literal>, <literal>lines</literal>,
<literal>proto</literal> and <literal>timeout</literal>. <literal>bytes</literal>
is used to provide the minimum number of bytes required for a read. <literal>lines</literal>
does the same, but for the minimum number of lines. If neither are provided, these
functions attempt to read as many bytes as are available. <literal>proto</literal>
is used to set the protocol to communicate with, defaulting to <literal>"tcp"</literal> if not provided.
<literal>timeout</literal> is used to set the socket timeout (see the socket function
<literal>set_timeout()</literal> for details).
</para>
<variablelist>
<varlistentry>
<term><option>bool, response = comm.get_banner(host, port, [options])</option>
</term>
<listitem>
<para>
This function simply connects to the specified port number on
the specified host and returns any data received.
<literal>bool</literal> is a Boolean value indicating success.
If <literal>bool</literal> is true, then the second returned
value is the response from the target host. If <literal>bool</literal>
is false, an error message is returned as the second value instead
of a response.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>bool, response = comm.exchange(host, port, data, [options])</option>
</term>
<listitem>
<para>
This function connects to the specified port number on the
specified host, sends <literal>data</literal>, then waits for
and returns the response, if any. <literal>bool</literal> is a
Boolean value indicating success. If <literal>bool</literal> is
true, then the second returned value is the response from the
target host. If <literal>bool</literal> is false, an error message
is returned as the second value instead of a response.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-unpwdb">
<title>Username/Password Database Functions</title>
@@ -2043,69 +1664,6 @@ if(s) code_to_be_done_on_match end
</variablelist>
</sect2>
<sect2 id="nse-lib-datafiles">
<title>Data File Parsing Functions</title>
<indexterm><primary><varname>datafiles</varname> NSE module</primary></indexterm>
<indexterm><primary>data files</primary><secondary>access to from NSE</secondary></indexterm>
<para>
The <literal>datafiles</literal> module provides functions for reading and parsing
Nmap's data files (e.g. <filename>nmap-protocol</filename>, <filename>nmap-rpc</filename>,
etc.). These functions' return values are setup for use with exception handling via
<literal>nmap.new_try()</literal>.
</para>
<variablelist>
<varlistentry>
<term><option>bool, table = datafiles.parse_protocols()</option>
</term>
<listitem>
<para>
This function reads and parses Nmap's <filename>nmap-protocols</filename>
file. <literal>bool</literal> is a Boolean value indicating success.
If <literal>bool</literal> is true, then the second returned
value is a table with protocol numbers indexing the protocol
names. If <literal>bool</literal> is false, an error message
is returned as the second value instead of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>bool, table = datafiles.parse_rpc()</option>
</term>
<listitem>
<para>
This function reads and parses Nmap's <filename>nmap-rpc</filename>
file. <literal>bool</literal> is a Boolean value indicating success.
If <literal>bool</literal> is true, then the second returned
value is a table with RPC numbers indexing the RPC names. If
<literal>bool</literal> is false, an error message is returned
as the second value instead of the table.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>bool, table = datafiles.parse_services([protocol])</option>
</term>
<listitem>
<para>
This function reads and parses Nmap's <filename>nmap-services</filename>
file. <literal>bool</literal> is a Boolean value indicating success.
If <literal>bool</literal> is true, then the second returned
value is a table containing two other tables:
<literal>tcp{}</literal> and <literal>udp{}</literal>.
<literal>tcp{}</literal> contains services indexed by TCP port
numbers. <literal>udp{}</literal> is the same, but for UDP.
You can pass <literal>"tcp"</literal> or <literal>"udp"</literal> as an argument to
<literal>parse_services()</literal> to only get the corresponding
table. If <literal>bool</literal> is false, an error message is
returned as the second value instead of the table.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="nse-lib-stdnse">
<title>Various Utility Functions</title>

61
nselib/comm.lua
View File

@@ -1,52 +1,23 @@
--- The comm module provides functions for common network discovery tasks.
-- Banner-grabbing and making a quick exchange of data are some of
-- these tasks. These
-- functions' return values are setup for use with exception handling
-- via nmap.new_try().\n
-- \n
-- These functions can all be passed a table of options, but it's not
-- required. The relevant indexes for this table are bytes, lines, proto
-- and timeout. bytes is used to provide the minimum number of bytes required
-- for a read. lines does the same, but for the minimum number of lines.
-- proto is used to set the protocol to communicate with, defaulting to
-- "tcp" if not provided. timeout is used to set the socket timeout (see
-- the socket function set_timeout() for details).
--- Common communication functions for network discovery tasks like
-- banner grabbing and data exchange.
-- \n\n
-- The functions in this module return values appropriate for use with
-- exception handling via nmap.new_try().
-- \n\n
-- These functions may be passed a table of options, but it's not
-- required. The keys for the options table are "bytes", "lines",
-- "proto", and "timeout". "bytes" sets a minimum number of bytes to
-- read. "lines" does the same for lines. "proto" sets the protocol to
-- communicate with, defaulting to "tcp" if not provided. "timeout" sets
-- the socket timeout (see the socket function set_timeout() for
-- details).
-- \n\n
-- If both "bytes" and "lines" are provided, "lines" takes precedence.
-- If neither are given, the functions read as many bytes as possible.
-- @author Kris Katterjohn 04/2008
module(... or "comm", package.seeall)
--
--
-- The Functions:
--
-- get_banner(host, port, [opts])
-- exchange(host, port, data, [opts])
--
-- get_banner() does just what it sounds like it does: connects to the
-- host, reads whatever it gives us, and then returns it.
--
-- exchange() connects to the host, sends the requested data, reads
-- whatever it gives us, and then returns it.
--
-- Both of these functions return multiple values so that they can be
-- used with exception handling via nmap.new_try(). The second value
-- they return is either the response from the host, or the error message
-- from one of the previous calls (connect, send, receive*).
--
-- These functions can be passed a table of options with the following keys:
--
-- bytes: Specifies the minimum amount of bytes are to be read from the host
-- lines: Specifies the minimum amount of lines are to be read from the host
-- proto: Specifies the protocol to be used with the connect() call
-- timeout: Sets the socket's timeout with nmap.set_timeout()
--
-- If neither lines nor bytes are specified, the calls attempt to read as many
-- bytes as possible. If only bytes is specified, then it only tries to read
-- that many bytes. Likewise, it only lines if specified, then it only tries
-- to read that many lines. If they're both specified, the lines value is used.
--
------
-- Makes sure that opts exists and the default proto is there
local initopts = function(opts)
if not opts then

85
nselib/datafiles.lua
View File

@@ -1,6 +1,10 @@
--- The datafiles module provides functions for reading and parsing Nmap's
-- data files. For example nmap-protocol, nmap-rpc, etc. These functions'
-- return values are setup for use with exception handling via nmap.new_try().
--- Read and parse some of Nmap's data files: nmap-protocol, nmap-rpc,
-- and nmap-services.
-- \n\n
-- The functions in this module return values appropriate for use with
-- exception handling via nmap.new_try(). On success, they return true
-- and the function result. On failure, they return false and an error
-- message.
-- @author Kris Katterjohn 03/2008
-- @author jah 08/2008
@@ -10,9 +14,10 @@ local stdnse = require "stdnse"
---
-- Holds tables containing captures for common data files, indexed by filename.
-- Capture patterns for common data files, indexed by filename.
-- @type table
-- @name common_files
-- @see parse_file
local common_files = {
["nmap-rpc"] = { [function(ln) return tonumber( ln:match( "^%s*[^%s#]+%s+(%d+)" ) ) end] = "^%s*([^%s#]+)%s+%d+" },
["nmap-protocols"] = { [function(ln) return tonumber( ln:match( "^%s*[^%s#]+%s+(%d+)" ) ) end] = "^%s*([^%s#]+)%s+%d+" },
@@ -24,11 +29,10 @@ local common_files = {
---
-- This function reads and parses Nmap's nmap-protocols file.
-- bool is a Boolean value indicating success. If bool is true, then the
-- second returned value is a table with protocol numbers indexing the
-- protocol names. If bool is false, an error message is returned as the
-- second value instead of the table.
-- Read and parse nmap-protocols.
-- \n\n
-- On success, return true and a table mapping protocol numbers to
-- protocol names.
-- @return bool, table|err
-- @see parse_file
parse_protocols = function()
@@ -42,11 +46,9 @@ end
---
-- This function reads and parses Nmap's nmap-rpc file. bool is a
-- Boolean value indicating success. If bool is true, then the second
-- returned value is a table with RPC numbers indexing the RPC names.
-- If bool is false, an error message is returned as the second value
-- instead of the table.
-- Read and parse nmap-rpc.
-- \n\n
-- On success, return true and a table mapping RPC numbers to RPC names.
-- @return bool, table|err
-- @see parse_file
parse_rpc = function()
@@ -60,15 +62,14 @@ end
---
-- This function reads and parses Nmap's nmap-services file.
-- bool is a Boolean value indicating success. If bool is true,
-- then the second returned value is a table containing two other
-- tables: tcp{} and udp{}. tcp{} contains services indexed by TCP port
-- numbers. udp{} is the same, but for UDP. You can pass "tcp" or "udp"
-- as an argument to parse_services() to only get the corresponding table.
-- If bool is false, an error message is returned as the second value instead
-- of the table.
-- @param protocol The protocol table to return.
-- Read and parse nmap-services.
-- \n\n
-- On success, return true and a table containing two subtables, indexed
-- by the keys "tcp" and "udp". The tcp table maps TCP port numbers to
-- service names, and the udp table is the same for UDP. You can pass
-- "tcp" or "udp" as an argument to parse_services to get only one of
-- the results tables.
-- @param protocol The protocol table to return ("tcp" of "udp").
-- @return bool, table|err
-- @see parse_file
parse_services = function(protocol)
@@ -86,11 +87,15 @@ end
---
-- Generic parsing of datafiles. By supplying this function with a table containing captures to be applied to each line
-- of a datafile a table will be returned which mirrors the structure of the supplied table and which contains any captured
-- values. A capture will be applied to each line using string.match() and may also be enclosed within a table or a function.
-- A function must accept a line as its parameter and should return one value derived from that line.
-- Read and parse a generic data file. The other parse functions are
-- defined in terms of this one.
-- \n\n
-- If filename is a key in common_files, use the corresponding capture
-- pattern. Otherwise the second argument must be a table of the kind
-- taken by parse_lines.
--
-- @return A table whose structure mirrors that of the capture table,
-- filled in with captured values.
function parse_file( filename, ... )
local data_struct
@@ -143,11 +148,16 @@ end
---
-- Generic parsing of an array of strings. By supplying this function with a table containing captures to be applied to each value
-- of a array-like table of strings a table will be returned which mirrors the structure of the supplied table and which contains any captured
-- values. A capture will be applied to each array member using string.match() and may also be enclosed within a table or a function.
-- A function must accept an array member as its parameter and should return one value derived from that member.
-- Generic parsing of an array of strings.
--
-- @param lines An array of strings to operate on.
-- @param data_struct A table containing capture patterns to be applied
-- to each string in the array. A capture will be applied to each string
-- using string.match() and may also be enclosed within a table or a
-- function. If a function, it must accept a string as its parameter and
-- should return one value derived from that string.
-- @return A table whose structure mirrors that of the capture table,
-- filled in with captured values.
function parse_lines( lines, data_struct )
if type( lines ) ~= "table" or #lines < 1 then
@@ -192,11 +202,10 @@ end
---
-- Reads a file, line by line, into a table.
-- Read a file, line by line, into a table.
-- @param file String with the name of the file to read.
-- @return Boolean True on success, False on error
-- @return Table (array-style) of lines read from the file or error message in case of an error.
function read_from_file( file )
-- get path to file
@@ -225,10 +234,9 @@ end
---
-- return an array-like table of values captured from each line
-- Return an array-like table of values captured from each line.
-- @param lines table of strings containing the lines to process
-- @param v_pattern pattern to use on the lines to produce the value for the array
get_array = function( lines, v_pattern )
local ret = {}
for _, line in ipairs( lines ) do
@@ -246,11 +254,10 @@ end
---
-- return an associative array table of index-value pairs captured from each line
-- Return an associative array table of index-value pairs captured from each line.
-- @param lines table of strings containing the lines to process
-- @param i_pattern pattern to use on the lines to produce the key for the associative array
-- @param v_pattern pattern to use on the lines to produce the value for the associative array
get_assoc_array = function( lines, i_pattern, v_pattern )
local ret = {}
for _, line in ipairs(lines) do

220
nselib/dns.lua
View File

@@ -1,7 +1,7 @@
module(... or "dns", package.seeall)
-- simple DNS library
-- packet creation, encoding, decoding, querying
--- Simple DNS library supporting packet creation, encoding, decoding,
-- and querying.
require("ipOps")
require("stdnse")
@@ -33,14 +33,13 @@ err = {
---
-- sends repeatedly udp packets to host,
-- waiting for an answer
--@param data Data to be sent
--@param host Host to connect to
--@param port Port to connect to
-- Repeatedly sends UDP packets to host, waiting for an answer.
--@param data Data to be sent.
--@param host Host to connect to.
--@param port Port to connect to.
--@param timeout Number of ms to wait for a response.
--@param cnt Number of tries
--@return success as boolean and response if available
--@param cnt Number of tries.
--@return success as boolean and response if available.
local function sendPackets(data, host, port, timeout, cnt)
local socket = nmap.new_socket()
socket:set_timeout(timeout)
@@ -62,9 +61,9 @@ end
---
-- Checks if DNS response packet contains a useful answer
--@param rPkt decoded DNS response packet
--@return True if useful, false if not
-- Checks if a DNS response packet contains a useful answer.
--@param rPkt decoded DNS response packet.
--@return true if useful, false if not.
local function gotAnswer(rPkt)
-- have we even got answers?
if #rPkt.answers > 0 then
@@ -93,8 +92,8 @@ end
---
-- Tries to find next nameserver with authority
-- to get result to query
-- Tries to find the next nameserver with authority to get a result for
-- query.
--@param rPkt decoded DNS response packet
--@return string or table of next server(s) to query or false
local function getAuthDns(rPkt)
@@ -124,16 +123,16 @@ local function getAuthDns(rPkt)
end
---
-- Query DNS servers for a DNS record
-- Query DNS servers for a DNS record.
--@param dname wanted domain name entry
--@param options
-- dtype wanted 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
--@param options \n
-- dtype wanted DNS record type (default: A).\n
-- host DNS server to be queried (default: DNS servers known to Nmap).\n
-- port Port of DNS server to connect to (default: 53).\n
-- tries How often should query try to contact another server (for non-recursive queries).\n
-- retAll Return all answers, not just the first.\n
-- retPkt Return the packet instead of using the answer fetching mechanism.\n
-- norecurse If true, do not set the recursion (RD) flags.\n
--@return Nice answer string by an answer fetcher on success or false and an error code (see: dns.err.*)
function query(dname, options)
if not options then options = {} end
@@ -226,9 +225,9 @@ end
---
-- Formats IP for reverse lookup
--@param ip IP address string
--@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa
-- Formats an IP address for reverse lookup.
--@param ip IP address string.
--@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa.
function reverse(ip)
ip = ipOps.expand_ip(ip)
if type(ip) ~= "string" then return nil end
@@ -262,14 +261,14 @@ function reverse(ip)
end
---
-- Table for answer fetching functions
-- Table for answer fetching functions.
local answerFetcher = {}
---
-- answer fetcher for TXT records
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return first entry (or all) treated as TXT
-- Answer fetcher for TXT records.
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return first entry (or all) treated as TXT.
answerFetcher[types.TXT] =
function(dec, retAll)
if not retAll then
@@ -284,10 +283,10 @@ answerFetcher[types.TXT] =
end
---
-- answer fetcher for A records
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return first IP (or all) of response packet
-- Answer fetcher for A records
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return first IP (or all) of response packet.
answerFetcher[types.A] =
function(dec, retAll)
local answers = {}
@@ -306,10 +305,10 @@ answerFetcher[types.A] =
---
-- answer fetcher for A records
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return Domain entry of first answer RR (or all) in response packet
-- Answer fetcher for CNAME records.
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return Domain entry of first answer RR (or all) in response packet.
answerFetcher[types.CNAME] =
function(dec, retAll)
if not retAll then
@@ -324,10 +323,10 @@ answerFetcher[types.CNAME] =
end
---
-- answer fetcher for A records
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return Domain entry of first answer RR (or all) in response packet
-- Answer fetcher for MX records.
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return Domain entry of first answer RR (or all) in response packet.
answerFetcher[types.MX] =
function(dec, retAll)
if not retAll then
@@ -350,10 +349,10 @@ answerFetcher[types.NS] = answerFetcher[types.CNAME]
answerFetcher[types.PTR] = answerFetcher[types.CNAME]
---
-- answer fetcher for AAAA records
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return first IPv6 (or all) of response packet
-- Answer fetcher for AAAA records.
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return first IPv6 (or all) of response packet.
answerFetcher[types.AAAA] =
function(dec, retAll)
local answers = {}
@@ -372,12 +371,12 @@ answerFetcher[types.AAAA] =
---
-- Calls answer fetcher for asked type or returns
-- error code on a no such name error
--@param dtype DNS resource record type
--@param dec Decoded DNS response
--@param retAll If true return all entries, not just the first
--@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error
-- Calls the answer fetcher for dtype or returns an error code on a no
-- such name error.
--@param dtype DNS resource record type.
--@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first.
--@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error.
function findNiceAnswer(dtype, dec, retAll)
if (#dec.answers > 0) then
if answerFetcher[dtype] then
@@ -393,9 +392,9 @@ end
---
-- Encodes the question part of a DNS request
--@param questions Table of questions
--@return Encoded question string
-- Encodes the question part of a DNS request.
--@param questions Table of questions.
--@return Encoded question string.
local function encodeQuestions(questions)
if type(questions) ~= "table" then return nil end
local encQ = ""
@@ -411,9 +410,9 @@ local function encodeQuestions(questions)
end
---
-- Encodes DNS flags to binary digit string
--@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx)
--@return Binary digit string representing flags
-- Encodes DNS flags to a binary digit string.
--@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx).
--@return Binary digit string representing flags.
local function encodeFlags(flags)
if type(flags) == "string" then return flags end
if type(flags) ~= "table" then return nil end
@@ -436,10 +435,10 @@ local function encodeFlags(flags)
end
---
-- Takes a table representing a DNS packet to encode
-- Caution: doesn't encode answer, authority and additional part
--@param pkt Table representing DNS packet, initialized by newPacket()
--@return Encoded DNS packet
-- Takes a table representing a DNS packet to encode.
-- Caution: doesn't encode answer, authority and additional part.
--@param pkt Table representing DNS packet, initialized by newPacket().
--@return Encoded DNS packet.
function encode(pkt)
if type(pkt) ~= "table" then return nil end
local encFlags = encodeFlags(pkt.flags)
@@ -450,11 +449,10 @@ end
---
-- Decodes a domain in a DNS packet,
-- handles "compressed" data, too
--@param data Complete DNS packet
--@param pos Starting position in packet
--@return Position after decoding and decoded domain
-- Decodes a domain in a DNS packet, Handles "compressed" data too.
--@param data Complete DNS packet.
--@param pos Starting position in packet.
--@return Position after decoding and decoded domain.
local function decStr(data, pos)
local partlen
local parts = {}
@@ -477,11 +475,11 @@ end
---
-- Decodes questions in a DNS packet
--@param data Complete DNS packet
--@param count Value of question counter in header
--@param pos Starting position in packet
--@return Position after decoding and table of decoded questions
-- Decodes questions in a DNS packet.
--@param data Complete DNS packet.
--@param count Value of question counter in header.
--@param pos Starting position in packet.
--@return Position after decoding and table of decoded questions.
local function decodeQuestions(data, count, pos)
local q = {}
for i = 1, count do
@@ -499,8 +497,8 @@ end
local decoder = {}
---
-- Decodes IP of A record, puts it in entry.ip
--@param entry RR in packet
-- Decodes IP of A record, puts it in entry.ip.
--@param entry RR in packet.
decoder[types.A] =
function(entry)
local ip = {}
@@ -510,8 +508,8 @@ decoder[types.A] =
end
---
-- Decodes IP of AAAA record, puts it in entry.ipv6
--@param entry RR in packet
-- Decodes IP of AAAA record, puts it in entry.ipv6.
--@param entry RR in packet.
decoder[types.AAAA] =
function(entry)
local ip = {}
@@ -525,12 +523,11 @@ decoder[types.AAAA] =
end
---
-- Decodes ssh fingerprint record, puts it
-- in entry.SSHFP as defined in RFC 4255:
-- Decodes SSH fingerprint record, puts it in entry.SSHFP as defined in RFC 4255:
-- .algorithm
-- .fptype
-- .fingerprint
--@param entry RR in packet
--@param entry RR in packet.
decoder[types.SSHFP] =
function(entry)
local _
@@ -541,7 +538,7 @@ decoder[types.SSHFP] =
---
-- Decodes SOA record, puts it in entry.SOA.*
-- Decodes SOA record, puts it in entry.SOA.*.
--@param entry RR in packet
--@param data Complete encoded DNS packet
--@param pos Position in packet after RR
@@ -563,12 +560,11 @@ decoder[types.SOA] =
end
---
-- Decodes records which consist only of one domain,
-- for example CNAME, NS, PTR.
-- Puts result in entry.domain
--@param entry RR in packet
--@param data Complete encoded DNS packet
--@param pos Position in packet after RR
-- Decodes records which consist only of one domain, for example CNAME,
-- NS, PTR. Puts result in entry.domain.
--@param entry RR in packet.
--@param data Complete encoded DNS packet.
--@param pos Position in packet after RR.
local function decDomain(entry, data, pos)
local np = pos - #entry.data
local _
@@ -584,10 +580,10 @@ decoder[types.PTR] = decDomain
decoder[types.TXT] = function () end
---
-- Decodes MX record, puts it in entry.MX.*
--@param entry RR in packet
--@param data Complete encoded DNS packet
--@param pos Position in packet after RR
-- Decodes MX record, puts it in entry.MX.*.
--@param entry RR in packet.
--@param data Complete encoded DNS packet.
--@param pos Position in packet after RR.
decoder[types.MX] =
function(entry, data, pos)
local np = pos - #entry.data + 2
@@ -599,12 +595,12 @@ decoder[types.MX] =
---
-- Decodes returned resource records (answer, authority
-- or additional part).
--@param data Complete encoded DNS packet
--@param count Value of according counter in header
--@param pos Starting position in packet
--@return Table of RRs
-- Decodes returned resource records (answer, authority or additional
-- part).
--@param data Complete encoded DNS packet.
--@param count Value of according counter in header.
--@param pos Starting position in packet.
--@return Table of RRs.
local function decodeRR(data, count, pos)
local ans = {}
for i = 1, count do
@@ -626,9 +622,9 @@ local function decodeRR(data, count, pos)
end
---
-- Splits string up into table of single characters
--@param str String to be split up
--@return Table of characters
-- Splits string up into table of single characters.
--@param str String to be split up.
--@return Table of characters.
local function str2tbl(str)
local tbl = {}
for i = 1, #str do
@@ -638,9 +634,9 @@ local function str2tbl(str)
end
---
-- Decodes DNS flags
--@param Flags as binary digit string
--@result Table representing flags
-- Decodes DNS flags.
--@param Flags as binary digit string.
--@result Table representing flags.
local function decodeFlags(flgStr)
flags = {}
flgTbl = str2tbl(flgStr)
@@ -661,9 +657,9 @@ local function decodeFlags(flgStr)
end
---
-- Decodes DNS packet
--@param data Encoded DNS packet
--@result Table representing DNS packet
-- Decodes a DNS packet.
--@param data Encoded DNS packet.
--@result Table representing DNS packet.
function decode(data)
local pos
local pkt = {}
@@ -686,8 +682,8 @@ end
---
-- Creates new table representing a DNS packet
--@return Table representing a DNS packet
-- Creates a new table representing a DNS packet.
--@return Table representing a DNS packet.
function newPacket()
local pkt = {}
pkt.id = 1
@@ -702,10 +698,10 @@ end
---
-- Adds a question to a DNS packet table
--@param pkt Table representing DNS packet
--@param dname Domain name to be asked
--@param dtype RR to be asked
-- Adds a question to a DNS packet table.
--@param pkt Table representing DNS packet.
--@param dname Domain name to be asked.
--@param dtype RR to be asked.
function addQuestion(pkt, dname, dtype)
if type(pkt) ~= "table" then return nil end
if type(pkt.questions) ~= "table" then return nil end

6
nselib/http.lua
View File

@@ -1,7 +1,7 @@
--- The http module provides functions for dealing with the client side
-- of the http protocol. The functions reside inside the http namespace.
--- Client-side HTTP library.
-- \n\n
-- The return value of each function in this module is a table with the
-- following keys: status, status-line, header and body. status is a number
-- following keys: status, status-line, header, and body. status is a number
-- representing the HTTP status code returned in response to the HTTP
-- request. In case of an unhandled error, status is nil. status-line is
-- the entire status message which includes the HTTP version, status code

30
nselib/ipOps.lua
View File

@@ -1,4 +1,4 @@
--- Provides functions for manipulating and comparing IP addresses. The functions reside inside the ipOps namespace.
--- Utility functions for manipulating and comparing IP addresses.
-- @copyright See Nmap License: <a href="http://nmap.org/book/man-legal.html">http://nmap.org/book/man-legal.html</a>
local type = type
@@ -14,7 +14,10 @@ module ( "ipOps" )
---
-- Checks to see if the supplied IP address is part of the following non-internet-routable address spaces:
-- Checks to see if the supplied IP address is part of a non-routable
-- address space.
-- \n\n
-- The non-Internet-routable address spaces known to this function are:
-- IPv4 Loopback (RFC3330),
-- IPv4 Private Use (RFC1918),
-- IPv4 Link Local (RFC3330),
@@ -53,8 +56,12 @@ end
---
-- Converts the supplied IPv4 address into a DWORD value.
-- i.e. the address <a.b.c.d> becomes (((a*256+b)*256+c)*256+d).
-- Note: Currently, numbers in NSE are limited to 10^14, consequently not all IPv6 addresses can be represented in base 10.
-- \n\n
-- For example, the address a.b.c.d becomes (((a*256+b)*256+c)*256+d).
-- \n\n
-- Note: IPv6 addresses are not supported. Currently, numbers in NSE are
-- limited to 10^14, consequently not all IPv6 addresses can be
-- represented in base 10.
-- @param ip String representing an IPv4 address. Shortened notation is permitted.
-- @usage local dword = ipOps.todword( "73.150.2.210" )
-- @return Number corresponding to the supplied IP address (or nil in case of an error).
@@ -78,10 +85,12 @@ end
---
-- Separates the supplied IP address into its constituent parts and returns them as a table of decimal numbers.
-- (e.g. the address 139.104.32.123 becomes { 139, 104, 32, 123 } )
-- @usage local a, b, c, d;
-- local t, err = get_parts_as_number( "139.104.32.123" );
-- Separates the supplied IP address into its constituent parts and
-- returns them as a table of decimal numbers.
-- \n\n
-- For example, the address 139.104.32.123 becomes { 139, 104, 32, 123 }.
-- @usage local a, b, c, d;\n
-- local t, err = get_parts_as_number( "139.104.32.123" );\n
-- if t then a, b, c, d = unpack( t ) end
-- @param ip String representing an IPv4 or IPv6 address. Shortened notation is permitted.
-- @return Array-style Table containing decimal numbers for each part of the supplied IP address (or nil in case of an error).
@@ -170,7 +179,9 @@ end
---
-- Checks whether the supplied IP address is within the supplied Range of IP addresses if they belong to the same address family.
-- Checks whether the supplied IP address is within the supplied range of IP addresses.
-- \n\n
-- The address and the range must both belong to the same address family.
-- @param ip String representing an IPv4 or IPv6 address. Shortened notation is permitted.
-- @param range String representing a range of IPv4 or IPv6 addresses in first-last or cidr notation (e.g. "192.168.1.1 - 192.168.255.255" or "2001:0A00::/23").
-- @usage if ipOps.ip_in_range( "192.168.1.1", "192/8" ) then ...
@@ -207,6 +218,7 @@ end
---
-- Expands an IP address supplied in shortened notation.
-- Serves also to check the well-formedness of an IP address.
-- \n\n
-- Note: IPv4in6 notated addresses will be returned in pure IPv6 notation unless the IPv4 portion
-- is shortened and does not contain a dot - in which case the address will be treated as IPv6.
-- @param ip String representing an IPv4 or IPv6 address in shortened or full notation.

39
nselib/listop.lua
View File

@@ -1,4 +1,5 @@
--- Functional Programming Style List Operations.\n\n
--- Functional-style list operations.
-- \n\n
-- People used to programming in functional languages, such as Lisp
-- or Haskell, appreciate their handling of lists very much. The listop
-- module tries to bring much of the functionality from functional languages
@@ -33,15 +34,15 @@ Functional programming style 'list' operations
where 'value' is an lua datatype
--]]
--- Determines if the list is empty.
--- Returns true if the given list is empty.
-- @param l A list.
-- @return boolean
function is_empty(l)
return #l == 0 and true or false;
end
--- Determines if l is a list (rather, a table).
-- @param l A list.
--- Returns true if the given value is a list (or rather a table).
-- @param l Any value.
-- @return boolean
function is_list(l)
return type(l) == 'table' and true or false;
@@ -49,6 +50,9 @@ end
--- Calls f for each element in the list. The returned list contains
-- the results of each function call.
-- \n\n
-- For example, listop.map(tostring,{1,2,true}) returns
-- {"1","2","true"}.
-- @param f The function to call.
-- @param l A list.
-- @return List
@@ -61,6 +65,8 @@ function map(f, l)
end
--- Calls the function with all the elements in the list as the parameters.
-- \n\n
-- For example, listop.apply(math.max,{1,5,6,7,50000}) yields 50000.
-- @param f The function to call.
-- @param l A list.
-- @return Results from f.
@@ -68,12 +74,14 @@ function apply(f, l)
return f(unpack(l))
end
--- Returns a list containing only those elements for which the predicate
-- returns true. The predicate has to be a function, which takes an element
-- of the list as argument and the result of which is interpreted as a
-- Boolean value. If it returns true (or rather anything besides false
-- and nil) the argument is appended to the return value of filter. For
-- example: listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns {1,2,3,4}.
--- Returns a list containing only those elements for which a predicate
-- function returns true.
-- \n\n
-- The predicate has to be a function taking one argument and returning
-- a Boolean. If it returns true (or rather anything besides false and
-- nil) the argument is appended to the return value of filter. For
-- example, listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns
-- {1,2,3,4}.
-- @param f The function.
-- @param l The list.
-- @return List
@@ -101,7 +109,7 @@ function cdr(l)
return {unpack(l, 2)}
end
--- Fetch element x from l.
--- Fetch element at index x from l.
-- @param l The List.
-- @param x Element index.
-- @return Element x or 1.
@@ -109,7 +117,7 @@ function ncar(l, x)
return l[x or 1];
end
--- Fetch all elements following the x or the first in a new List.
--- Fetch all elements following the element at index x or the first.
-- @param l The List.
-- @param x Element index.
-- @return List
@@ -149,8 +157,11 @@ function reverse(l)
return results
end
--- Return a flattened version of the List, l. All lists within l are
-- replaced by its contents.
--- Return a flattened version of a list. The flattened list contains
-- only non-list values.
-- \n\n
-- For example, listop.flatten({1,2,3,"foo",{4,5,{"bar"}}}) returns
-- {1,2,3,"foo",4,5,"bar"}.
-- @param l The list to flatten.
-- @return List
function flatten(l)

31
nselib/match.lua
View File

@@ -1,5 +1,7 @@
--- Provides functions which can be used for delimiting data received
-- by receive_buf() function in the Network I/O API.
--- Buffered network I/O helper functions.
-- \n\n
-- The functions in this module can be used for delimiting data received
-- by the receive_buf function in the Network I/O API.
--@copyright See nmaps COPYING for licence
module(... or "match", package.seeall)
@@ -14,13 +16,13 @@ require "pcre"
-- sock:receive_bytes(80) - i.e. it returns
-- exactly 80 bytes and no more
--- This is actually a wrapper around NSE's PCRE library exec function,
-- thus giving script developers the possibility to use regular expressions
-- for delimiting instead of Lua's string patterns. If you want to get the
-- data in chunks separated by pattern (which has to be a valid regular
-- expression), you would write:
-- status, val = sockobj:receive_buf(match.regex("pattern")).
--- Return a function that allows delimiting with a regular expression.
-- \n\n
-- This function is a wrapper around the exec function of the pcre
-- library. It purpose is to give script developers the ability to use
-- regular expressions for delimiting instead of Lua's string patterns.
-- @param The regex.
-- @usage sock:receivebuf(regex("myregexpattern"))
regex = function(pattern)
local r = pcre.new(pattern, 0,"C")
@@ -30,12 +32,15 @@ regex = function(pattern)
end
end
--- Takes a number as its argument and returns that many bytes. It can be
-- used to get a buffered version of sockobj:receive_bytes(n) in case a
-- script requires more than one fixed-size chunk, as the unbuffered
-- version may return more bytes than requested and thus would require
-- you to do the parsing on your own.
--- Return a function that allows delimiting at a certain number of bytes.
-- \n\n
-- This function can be used to get a buffered version of
-- sockobj:receive_bytes(n) in case a script requires more than one
-- fixed-size chunk, as the unbuffered version may return more bytes
-- than requested and thus would require you to do the parsing on your
-- own.
-- @param num Number of bytes.
-- @usage sock:receivebuf(numbytes(80))
numbytes = function(num)
local n = num
return function(buf)