PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2026-01-03 05:09:14 +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>