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"/> <indexterm class="endofrange" startref="nse-openssl-indexterm"/>
</sect2> </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"> <sect2 id="nse-lib-shortport">
<title>Short Portrules</title> <title>Short Portrules</title>
<indexterm><primary><varname>shortport</varname> NSE module</primary></indexterm> <indexterm><primary><varname>shortport</varname> NSE module</primary></indexterm>
@@ -1527,159 +1480,6 @@ if(s) code_to_be_done_on_match end
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</sect2> </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"> <sect2 id="nse-lib-strbuf">
<title>String Buffer Operations</title> <title>String Buffer Operations</title>
<indexterm><primary><varname>strbuf</varname> NSE module</primary></indexterm> <indexterm><primary><varname>strbuf</varname> NSE module</primary></indexterm>
@@ -1802,185 +1602,6 @@ if(s) code_to_be_done_on_match end
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</sect2> </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"> <sect2 id="nse-lib-unpwdb">
<title>Username/Password Database Functions</title> <title>Username/Password Database Functions</title>
@@ -2043,69 +1664,6 @@ if(s) code_to_be_done_on_match end
</variablelist> </variablelist>
</sect2> </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>
<sect2 id="nse-lib-stdnse"> <sect2 id="nse-lib-stdnse">
<title>Various Utility Functions</title> <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. --- Common communication functions for network discovery tasks like
-- Banner-grabbing and making a quick exchange of data are some of -- banner grabbing and data exchange.
-- these tasks. These -- \n\n
-- functions' return values are setup for use with exception handling -- The functions in this module return values appropriate for use with
-- via nmap.new_try().\n -- exception handling via nmap.new_try().
-- \n -- \n\n
-- These functions can all be passed a table of options, but it's not -- These functions may be passed a table of options, but it's not
-- required. The relevant indexes for this table are bytes, lines, proto -- required. The keys for the options table are "bytes", "lines",
-- and timeout. bytes is used to provide the minimum number of bytes required -- "proto", and "timeout". "bytes" sets a minimum number of bytes to
-- for a read. lines does the same, but for the minimum number of lines. -- read. "lines" does the same for lines. "proto" sets the protocol to
-- proto is used to set the protocol to communicate with, defaulting to -- communicate with, defaulting to "tcp" if not provided. "timeout" sets
-- "tcp" if not provided. timeout is used to set the socket timeout (see -- the socket timeout (see the socket function set_timeout() for
-- the socket function set_timeout() for details). -- 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 -- @author Kris Katterjohn 04/2008
module(... or "comm", package.seeall) 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 -- Makes sure that opts exists and the default proto is there
local initopts = function(opts) local initopts = function(opts)
if not opts then 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 --- Read and parse some of Nmap's data files: nmap-protocol, nmap-rpc,
-- data files. For example nmap-protocol, nmap-rpc, etc. These functions' -- and nmap-services.
-- return values are setup for use with exception handling via nmap.new_try(). -- \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 Kris Katterjohn 03/2008
-- @author jah 08/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 -- @type table
-- @name common_files -- @name common_files
-- @see parse_file
local common_files = { local common_files = {
["nmap-rpc"] = { [function(ln) return tonumber( ln:match( "^%s*[^%s#]+%s+(%d+)" ) ) end] = "^%s*([^%s#]+)%s+%d+" }, ["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+" }, ["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. -- Read and parse nmap-protocols.
-- bool is a Boolean value indicating success. If bool is true, then the -- \n\n
-- second returned value is a table with protocol numbers indexing the -- On success, return true and a table mapping protocol numbers to
-- protocol names. If bool is false, an error message is returned as the -- protocol names.
-- second value instead of the table.
-- @return bool, table|err -- @return bool, table|err
-- @see parse_file -- @see parse_file
parse_protocols = function() parse_protocols = function()
@@ -42,11 +46,9 @@ end
--- ---
-- This function reads and parses Nmap's nmap-rpc file. bool is a -- Read and parse nmap-rpc.
-- Boolean value indicating success. If bool is true, then the second -- \n\n
-- returned value is a table with RPC numbers indexing the RPC names. -- On success, return true and a table mapping RPC numbers to RPC names.
-- If bool is false, an error message is returned as the second value
-- instead of the table.
-- @return bool, table|err -- @return bool, table|err
-- @see parse_file -- @see parse_file
parse_rpc = function() parse_rpc = function()
@@ -60,15 +62,14 @@ end
--- ---
-- This function reads and parses Nmap's nmap-services file. -- Read and parse nmap-services.
-- bool is a Boolean value indicating success. If bool is true, -- \n\n
-- then the second returned value is a table containing two other -- On success, return true and a table containing two subtables, indexed
-- tables: tcp{} and udp{}. tcp{} contains services indexed by TCP port -- by the keys "tcp" and "udp". The tcp table maps TCP port numbers to
-- numbers. udp{} is the same, but for UDP. You can pass "tcp" or "udp" -- service names, and the udp table is the same for UDP. You can pass
-- as an argument to parse_services() to only get the corresponding table. -- "tcp" or "udp" as an argument to parse_services to get only one of
-- If bool is false, an error message is returned as the second value instead -- the results tables.
-- of the table. -- @param protocol The protocol table to return ("tcp" of "udp").
-- @param protocol The protocol table to return.
-- @return bool, table|err -- @return bool, table|err
-- @see parse_file -- @see parse_file
parse_services = function(protocol) 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 -- Read and parse a generic data file. The other parse functions are
-- of a datafile a table will be returned which mirrors the structure of the supplied table and which contains any captured -- defined in terms of this one.
-- values. A capture will be applied to each line using string.match() and may also be enclosed within a table or a function. -- \n\n
-- A function must accept a line as its parameter and should return one value derived from that line. -- 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, ... ) function parse_file( filename, ... )
local data_struct 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 -- Generic parsing of an array of strings.
-- 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. -- @param lines An array of strings to operate on.
-- A function must accept an array member as its parameter and should return one value derived from that member. -- @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 ) function parse_lines( lines, data_struct )
if type( lines ) ~= "table" or #lines < 1 then 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. -- @param file String with the name of the file to read.
-- @return Boolean True on success, False on error -- @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. -- @return Table (array-style) of lines read from the file or error message in case of an error.
function read_from_file( file ) function read_from_file( file )
-- get path to 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 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 -- @param v_pattern pattern to use on the lines to produce the value for the array
get_array = function( lines, v_pattern ) get_array = function( lines, v_pattern )
local ret = {} local ret = {}
for _, line in ipairs( lines ) do 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 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 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 -- @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 ) get_assoc_array = function( lines, i_pattern, v_pattern )
local ret = {} local ret = {}
for _, line in ipairs(lines) do for _, line in ipairs(lines) do

220
nselib/dns.lua
View File

@@ -1,7 +1,7 @@
module(... or "dns", package.seeall) module(... or "dns", package.seeall)
-- simple DNS library --- Simple DNS library supporting packet creation, encoding, decoding,
-- packet creation, encoding, decoding, querying -- and querying.
require("ipOps") require("ipOps")
require("stdnse") require("stdnse")
@@ -33,14 +33,13 @@ err = {
--- ---
-- sends repeatedly udp packets to host, -- Repeatedly sends UDP packets to host, waiting for an answer.
-- waiting for an answer --@param data Data to be sent.
--@param data Data to be sent --@param host Host to connect to.
--@param host Host to connect to --@param port Port to connect to.
--@param port Port to connect to
--@param timeout Number of ms to wait for a response. --@param timeout Number of ms to wait for a response.
--@param cnt Number of tries --@param cnt Number of tries.
--@return success as boolean and response if available --@return success as boolean and response if available.
local function sendPackets(data, host, port, timeout, cnt) local function sendPackets(data, host, port, timeout, cnt)
local socket = nmap.new_socket() local socket = nmap.new_socket()
socket:set_timeout(timeout) socket:set_timeout(timeout)
@@ -62,9 +61,9 @@ end
--- ---
-- Checks if DNS response packet contains a useful answer -- Checks if a DNS response packet contains a useful answer.
--@param rPkt decoded DNS response packet --@param rPkt decoded DNS response packet.
--@return True if useful, false if not --@return true if useful, false if not.
local function gotAnswer(rPkt) local function gotAnswer(rPkt)
-- have we even got answers? -- have we even got answers?
if #rPkt.answers > 0 then if #rPkt.answers > 0 then
@@ -93,8 +92,8 @@ end
--- ---
-- Tries to find next nameserver with authority -- Tries to find the next nameserver with authority to get a result for
-- to get result to query -- query.
--@param rPkt decoded DNS response packet --@param rPkt decoded DNS response packet
--@return string or table of next server(s) to query or false --@return string or table of next server(s) to query or false
local function getAuthDns(rPkt) local function getAuthDns(rPkt)
@@ -124,16 +123,16 @@ local function getAuthDns(rPkt)
end end
--- ---
-- Query DNS servers for a DNS record -- Query DNS servers for a DNS record.
--@param dname wanted domain name entry --@param dname wanted domain name entry
--@param options --@param options \n
-- dtype wanted DNS record type (default: A) -- dtype wanted DNS record type (default: A).\n
-- host DNS server to be queried (default: DNS servers known to nmap) -- host DNS server to be queried (default: DNS servers known to Nmap).\n
-- port Port of DNS server to connect to (default: 53) -- 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) -- tries How often should query try to contact another server (for non-recursive queries).\n
-- retAll Return all answers, not just the first -- retAll Return all answers, not just the first.\n
-- retPkt Return the packet instead of using the answer fetching mechanism -- retPkt Return the packet instead of using the answer fetching mechanism.\n
-- norecurse -- 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.*) --@return Nice answer string by an answer fetcher on success or false and an error code (see: dns.err.*)
function query(dname, options) function query(dname, options)
if not options then options = {} end if not options then options = {} end
@@ -226,9 +225,9 @@ end
--- ---
-- Formats IP for reverse lookup -- Formats an IP address for reverse lookup.
--@param ip IP address string --@param ip IP address string.
--@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa --@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa.
function reverse(ip) function reverse(ip)
ip = ipOps.expand_ip(ip) ip = ipOps.expand_ip(ip)
if type(ip) ~= "string" then return nil end if type(ip) ~= "string" then return nil end
@@ -262,14 +261,14 @@ function reverse(ip)
end end
--- ---
-- Table for answer fetching functions -- Table for answer fetching functions.
local answerFetcher = {} local answerFetcher = {}
--- ---
-- answer fetcher for TXT records -- Answer fetcher for TXT records.
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@param retAll If true return all entries, not just the first.
--@return first entry (or all) treated as TXT --@return first entry (or all) treated as TXT.
answerFetcher[types.TXT] = answerFetcher[types.TXT] =
function(dec, retAll) function(dec, retAll)
if not retAll then if not retAll then
@@ -284,10 +283,10 @@ answerFetcher[types.TXT] =
end end
--- ---
-- answer fetcher for A records -- Answer fetcher for A records
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@param retAll If true return all entries, not just the first.
--@return first IP (or all) of response packet --@return first IP (or all) of response packet.
answerFetcher[types.A] = answerFetcher[types.A] =
function(dec, retAll) function(dec, retAll)
local answers = {} local answers = {}
@@ -306,10 +305,10 @@ answerFetcher[types.A] =
--- ---
-- answer fetcher for A records -- Answer fetcher for CNAME records.
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@param retAll If true return all entries, not just the first.
--@return Domain entry of first answer RR (or all) in response packet --@return Domain entry of first answer RR (or all) in response packet.
answerFetcher[types.CNAME] = answerFetcher[types.CNAME] =
function(dec, retAll) function(dec, retAll)
if not retAll then if not retAll then
@@ -324,10 +323,10 @@ answerFetcher[types.CNAME] =
end end
--- ---
-- answer fetcher for A records -- Answer fetcher for MX records.
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@param retAll If true return all entries, not just the first.
--@return Domain entry of first answer RR (or all) in response packet --@return Domain entry of first answer RR (or all) in response packet.
answerFetcher[types.MX] = answerFetcher[types.MX] =
function(dec, retAll) function(dec, retAll)
if not retAll then if not retAll then
@@ -350,10 +349,10 @@ answerFetcher[types.NS] = answerFetcher[types.CNAME]
answerFetcher[types.PTR] = answerFetcher[types.CNAME] answerFetcher[types.PTR] = answerFetcher[types.CNAME]
--- ---
-- answer fetcher for AAAA records -- Answer fetcher for AAAA records.
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@param retAll If true return all entries, not just the first.
--@return first IPv6 (or all) of response packet --@return first IPv6 (or all) of response packet.
answerFetcher[types.AAAA] = answerFetcher[types.AAAA] =
function(dec, retAll) function(dec, retAll)
local answers = {} local answers = {}
@@ -372,12 +371,12 @@ answerFetcher[types.AAAA] =
--- ---
-- Calls answer fetcher for asked type or returns -- Calls the answer fetcher for dtype or returns an error code on a no
-- error code on a no such name error -- such name error.
--@param dtype DNS resource record type --@param dtype DNS resource record type.
--@param dec Decoded DNS response --@param dec Decoded DNS response.
--@param retAll If true return all entries, not just the first --@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 --@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) function findNiceAnswer(dtype, dec, retAll)
if (#dec.answers > 0) then if (#dec.answers > 0) then
if answerFetcher[dtype] then if answerFetcher[dtype] then
@@ -393,9 +392,9 @@ end
--- ---
-- Encodes the question part of a DNS request -- Encodes the question part of a DNS request.
--@param questions Table of questions --@param questions Table of questions.
--@return Encoded question string --@return Encoded question string.
local function encodeQuestions(questions) local function encodeQuestions(questions)
if type(questions) ~= "table" then return nil end if type(questions) ~= "table" then return nil end
local encQ = "" local encQ = ""
@@ -411,9 +410,9 @@ local function encodeQuestions(questions)
end end
--- ---
-- Encodes DNS flags to binary digit string -- Encodes DNS flags to a binary digit string.
--@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx) --@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx).
--@return Binary digit string representing flags --@return Binary digit string representing flags.
local function encodeFlags(flags) local function encodeFlags(flags)
if type(flags) == "string" then return flags end if type(flags) == "string" then return flags end
if type(flags) ~= "table" then return nil end if type(flags) ~= "table" then return nil end
@@ -436,10 +435,10 @@ local function encodeFlags(flags)
end end
--- ---
-- Takes a table representing a DNS packet to encode -- Takes a table representing a DNS packet to encode.
-- Caution: doesn't encode answer, authority and additional part -- Caution: doesn't encode answer, authority and additional part.
--@param pkt Table representing DNS packet, initialized by newPacket() --@param pkt Table representing DNS packet, initialized by newPacket().
--@return Encoded DNS packet --@return Encoded DNS packet.
function encode(pkt) function encode(pkt)
if type(pkt) ~= "table" then return nil end if type(pkt) ~= "table" then return nil end
local encFlags = encodeFlags(pkt.flags) local encFlags = encodeFlags(pkt.flags)
@@ -450,11 +449,10 @@ end
--- ---
-- Decodes a domain in a DNS packet, -- Decodes a domain in a DNS packet, Handles "compressed" data too.
-- handles "compressed" data, too --@param data Complete DNS packet.
--@param data Complete DNS packet --@param pos Starting position in packet.
--@param pos Starting position in packet --@return Position after decoding and decoded domain.
--@return Position after decoding and decoded domain
local function decStr(data, pos) local function decStr(data, pos)
local partlen local partlen
local parts = {} local parts = {}
@@ -477,11 +475,11 @@ end
--- ---
-- Decodes questions in a DNS packet -- Decodes questions in a DNS packet.
--@param data Complete DNS packet --@param data Complete DNS packet.
--@param count Value of question counter in header --@param count Value of question counter in header.
--@param pos Starting position in packet --@param pos Starting position in packet.
--@return Position after decoding and table of decoded questions --@return Position after decoding and table of decoded questions.
local function decodeQuestions(data, count, pos) local function decodeQuestions(data, count, pos)
local q = {} local q = {}
for i = 1, count do for i = 1, count do
@@ -499,8 +497,8 @@ end
local decoder = {} local decoder = {}
--- ---
-- Decodes IP of A record, puts it in entry.ip -- Decodes IP of A record, puts it in entry.ip.
--@param entry RR in packet --@param entry RR in packet.
decoder[types.A] = decoder[types.A] =
function(entry) function(entry)
local ip = {} local ip = {}
@@ -510,8 +508,8 @@ decoder[types.A] =
end end
--- ---
-- Decodes IP of AAAA record, puts it in entry.ipv6 -- Decodes IP of AAAA record, puts it in entry.ipv6.
--@param entry RR in packet --@param entry RR in packet.
decoder[types.AAAA] = decoder[types.AAAA] =
function(entry) function(entry)
local ip = {} local ip = {}
@@ -525,12 +523,11 @@ decoder[types.AAAA] =
end end
--- ---
-- Decodes ssh fingerprint record, puts it -- Decodes SSH fingerprint record, puts it in entry.SSHFP as defined in RFC 4255:
-- in entry.SSHFP as defined in RFC 4255:
-- .algorithm -- .algorithm
-- .fptype -- .fptype
-- .fingerprint -- .fingerprint
--@param entry RR in packet --@param entry RR in packet.
decoder[types.SSHFP] = decoder[types.SSHFP] =
function(entry) function(entry)
local _ 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 entry RR in packet
--@param data Complete encoded DNS packet --@param data Complete encoded DNS packet
--@param pos Position in packet after RR --@param pos Position in packet after RR
@@ -563,12 +560,11 @@ decoder[types.SOA] =
end end
--- ---
-- Decodes records which consist only of one domain, -- Decodes records which consist only of one domain, for example CNAME,
-- for example CNAME, NS, PTR. -- NS, PTR. Puts result in entry.domain.
-- Puts result in entry.domain --@param entry RR in packet.
--@param entry RR in packet --@param data Complete encoded DNS packet.
--@param data Complete encoded DNS packet --@param pos Position in packet after RR.
--@param pos Position in packet after RR
local function decDomain(entry, data, pos) local function decDomain(entry, data, pos)
local np = pos - #entry.data local np = pos - #entry.data
local _ local _
@@ -584,10 +580,10 @@ decoder[types.PTR] = decDomain
decoder[types.TXT] = function () end decoder[types.TXT] = function () end
--- ---
-- Decodes MX record, puts it in entry.MX.* -- Decodes MX record, puts it in entry.MX.*.
--@param entry RR in packet --@param entry RR in packet.
--@param data Complete encoded DNS packet --@param data Complete encoded DNS packet.
--@param pos Position in packet after RR --@param pos Position in packet after RR.
decoder[types.MX] = decoder[types.MX] =
function(entry, data, pos) function(entry, data, pos)
local np = pos - #entry.data + 2 local np = pos - #entry.data + 2
@@ -599,12 +595,12 @@ decoder[types.MX] =
--- ---
-- Decodes returned resource records (answer, authority -- Decodes returned resource records (answer, authority or additional
-- or additional part). -- part).
--@param data Complete encoded DNS packet --@param data Complete encoded DNS packet.
--@param count Value of according counter in header --@param count Value of according counter in header.
--@param pos Starting position in packet --@param pos Starting position in packet.
--@return Table of RRs --@return Table of RRs.
local function decodeRR(data, count, pos) local function decodeRR(data, count, pos)
local ans = {} local ans = {}
for i = 1, count do for i = 1, count do
@@ -626,9 +622,9 @@ local function decodeRR(data, count, pos)
end end
--- ---
-- Splits string up into table of single characters -- Splits string up into table of single characters.
--@param str String to be split up --@param str String to be split up.
--@return Table of characters --@return Table of characters.
local function str2tbl(str) local function str2tbl(str)
local tbl = {} local tbl = {}
for i = 1, #str do for i = 1, #str do
@@ -638,9 +634,9 @@ local function str2tbl(str)
end end
--- ---
-- Decodes DNS flags -- Decodes DNS flags.
--@param Flags as binary digit string --@param Flags as binary digit string.
--@result Table representing flags --@result Table representing flags.
local function decodeFlags(flgStr) local function decodeFlags(flgStr)
flags = {} flags = {}
flgTbl = str2tbl(flgStr) flgTbl = str2tbl(flgStr)
@@ -661,9 +657,9 @@ local function decodeFlags(flgStr)
end end
--- ---
-- Decodes DNS packet -- Decodes a DNS packet.
--@param data Encoded DNS packet --@param data Encoded DNS packet.
--@result Table representing DNS packet --@result Table representing DNS packet.
function decode(data) function decode(data)
local pos local pos
local pkt = {} local pkt = {}
@@ -686,8 +682,8 @@ end
--- ---
-- Creates new table representing a DNS packet -- Creates a new table representing a DNS packet.
--@return Table representing a DNS packet --@return Table representing a DNS packet.
function newPacket() function newPacket()
local pkt = {} local pkt = {}
pkt.id = 1 pkt.id = 1
@@ -702,10 +698,10 @@ end
--- ---
-- Adds a question to a DNS packet table -- Adds a question to a DNS packet table.
--@param pkt Table representing DNS packet --@param pkt Table representing DNS packet.
--@param dname Domain name to be asked --@param dname Domain name to be asked.
--@param dtype RR to be asked --@param dtype RR to be asked.
function addQuestion(pkt, dname, dtype) function addQuestion(pkt, dname, dtype)
if type(pkt) ~= "table" then return nil end if type(pkt) ~= "table" then return nil end
if type(pkt.questions) ~= "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 --- Client-side HTTP library.
-- of the http protocol. The functions reside inside the http namespace. -- \n\n
-- The return value of each function in this module is a table with the -- 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 -- representing the HTTP status code returned in response to the HTTP
-- request. In case of an unhandled error, status is nil. status-line is -- request. In case of an unhandled error, status is nil. status-line is
-- the entire status message which includes the HTTP version, status code -- 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> -- @copyright See Nmap License: <a href="http://nmap.org/book/man-legal.html">http://nmap.org/book/man-legal.html</a>
local type = type 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 Loopback (RFC3330),
-- IPv4 Private Use (RFC1918), -- IPv4 Private Use (RFC1918),
-- IPv4 Link Local (RFC3330), -- IPv4 Link Local (RFC3330),
@@ -53,8 +56,12 @@ end
--- ---
-- Converts the supplied IPv4 address into a DWORD value. -- 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). -- \n\n
-- Note: Currently, numbers in NSE are limited to 10^14, consequently not all IPv6 addresses can be represented in base 10. -- 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. -- @param ip String representing an IPv4 address. Shortened notation is permitted.
-- @usage local dword = ipOps.todword( "73.150.2.210" ) -- @usage local dword = ipOps.todword( "73.150.2.210" )
-- @return Number corresponding to the supplied IP address (or nil in case of an error). -- @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. -- Separates the supplied IP address into its constituent parts and
-- (e.g. the address 139.104.32.123 becomes { 139, 104, 32, 123 } ) -- returns them as a table of decimal numbers.
-- @usage local a, b, c, d; -- \n\n
-- local t, err = get_parts_as_number( "139.104.32.123" ); -- 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 -- if t then a, b, c, d = unpack( t ) end
-- @param ip String representing an IPv4 or IPv6 address. Shortened notation is permitted. -- @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). -- @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 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"). -- @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 ... -- @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. -- Expands an IP address supplied in shortened notation.
-- Serves also to check the well-formedness of an IP address. -- 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 -- 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. -- 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. -- @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 -- People used to programming in functional languages, such as Lisp
-- or Haskell, appreciate their handling of lists very much. The listop -- or Haskell, appreciate their handling of lists very much. The listop
-- module tries to bring much of the functionality from functional languages -- 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 where 'value' is an lua datatype
--]] --]]
--- Determines if the list is empty. --- Returns true if the given list is empty.
-- @param l A list. -- @param l A list.
-- @return boolean -- @return boolean
function is_empty(l) function is_empty(l)
return #l == 0 and true or false; return #l == 0 and true or false;
end end
--- Determines if l is a list (rather, a table). --- Returns true if the given value is a list (or rather a table).
-- @param l A list. -- @param l Any value.
-- @return boolean -- @return boolean
function is_list(l) function is_list(l)
return type(l) == 'table' and true or false; 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 --- Calls f for each element in the list. The returned list contains
-- the results of each function call. -- 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 f The function to call.
-- @param l A list. -- @param l A list.
-- @return List -- @return List
@@ -61,6 +65,8 @@ function map(f, l)
end end
--- Calls the function with all the elements in the list as the parameters. --- 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 f The function to call.
-- @param l A list. -- @param l A list.
-- @return Results from f. -- @return Results from f.
@@ -68,12 +74,14 @@ function apply(f, l)
return f(unpack(l)) return f(unpack(l))
end end
--- Returns a list containing only those elements for which the predicate --- Returns a list containing only those elements for which a predicate
-- returns true. The predicate has to be a function, which takes an element -- function returns true.
-- of the list as argument and the result of which is interpreted as a -- \n\n
-- Boolean value. If it returns true (or rather anything besides false -- The predicate has to be a function taking one argument and returning
-- and nil) the argument is appended to the return value of filter. For -- a Boolean. If it returns true (or rather anything besides false and
-- example: listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns {1,2,3,4}. -- 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 f The function.
-- @param l The list. -- @param l The list.
-- @return List -- @return List
@@ -101,7 +109,7 @@ function cdr(l)
return {unpack(l, 2)} return {unpack(l, 2)}
end end
--- Fetch element x from l. --- Fetch element at index x from l.
-- @param l The List. -- @param l The List.
-- @param x Element index. -- @param x Element index.
-- @return Element x or 1. -- @return Element x or 1.
@@ -109,7 +117,7 @@ function ncar(l, x)
return l[x or 1]; return l[x or 1];
end 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 l The List.
-- @param x Element index. -- @param x Element index.
-- @return List -- @return List
@@ -149,8 +157,11 @@ function reverse(l)
return results return results
end end
--- Return a flattened version of the List, l. All lists within l are --- Return a flattened version of a list. The flattened list contains
-- replaced by its contents. -- 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. -- @param l The list to flatten.
-- @return List -- @return List
function flatten(l) function flatten(l)

31
nselib/match.lua
View File

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