mirror of
https://github.com/nmap/nmap.git
synced 2025-12-14 19:59:02 +00:00
Merge documetation for unpwdb, url, bit, tab, base64, and bin.
This commit is contained in:
david
@@ -777,209 +777,6 @@ action refer to <xref linkend="nse-tutorial-action"/>.
|
||||
The default modules are described in the following sections.
|
||||
</para>
|
||||
|
||||
<sect2 id="nse-bitops">
|
||||
<title>Bitwise Logical Operations</title>
|
||||
<indexterm><primary><varname>bit</varname> NSE module</primary></indexterm>
|
||||
<para>
|
||||
Lua does not provide
|
||||
bitwise logical operations.<indexterm><primary>bitwise operations in NSE</primary></indexterm>
|
||||
Since they
|
||||
are often useful for low-level network communication,
|
||||
Reuben Thomas'<indexterm><primary>Thomas, Reuben</primary></indexterm>
|
||||
<ulink url="http://luaforge.net/projects/bitlib">bitwise operation library</ulink>
|
||||
for Lua has been
|
||||
integrated into NSE. The arguments to the bitwise operation
|
||||
functions should be integers. The number of bits available
|
||||
for logical operations depends on the data type used to
|
||||
represent Lua numbers—this is typically 8-byte IEEE
|
||||
floats (double), which give 53 bits (the size of the mantissa).
|
||||
|
||||
This implies that the bitwise operations won't work (as expected)
|
||||
for numbers larger than 10<superscript>14</superscript>. You
|
||||
can use them with 32-bit wide numbers without any problems. Operations
|
||||
involving 64-bit wide numbers, however, may not return the expected
|
||||
result.
|
||||
The logical operations start with <quote>b</quote> (for <literal>bit</literal>) to avoid
|
||||
clashing with reserved words; although <literal>xor</literal> isn't a
|
||||
reserved word, it seemed better to use <literal>bxor</literal> for
|
||||
consistency. In NSE the bitwise functions are in the <literal>bit</literal>
|
||||
namespace.
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>bit.bnot(a)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the one's complement of <literal>a</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.band(w1,...)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the bitwise <literal>and</literal> of the
|
||||
<literal>w</literal> variables.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.bor(w1,...)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the bitwise <literal>or</literal> of the <literal>w</literal> variables.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.bxor(w1,...)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
|
||||
<para>
|
||||
Returns the bitwise <literal>xor</literal> of the <literal>w</literal> variables.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.lshift(a,b)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns <literal>a</literal> shifted left <literal>b</literal> places—padded with zeros.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.rshift(a,b)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns <literal>a</literal> shifted logically right <literal>b</literal> places.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.arshift(a,b)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns <literal>a</literal> shifted arithmetically right <literal>b</literal> places.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bit.mod(a,b)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the integer remainder of <literal>a</literal> divided by <literal>b</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="nse-binlib">
|
||||
<title>Binary Data Handling</title>
|
||||
<indexterm><primary><varname>bin</varname> NSE module</primary></indexterm>
|
||||
<para>
|
||||
A problem script authors often face is the necessity of encoding values
|
||||
into binary data. For example after analyzing a protocol the starting
|
||||
point to write a script could be a hex dump, which serves as a preamble
|
||||
to every sent packet. Although it is possible work with the
|
||||
functionality Lua provides, it's not very convenient. Therefore the
|
||||
Binlib has been added to NSE, based on
|
||||
<ulink url="http://www.tecgraf.puc-rio.br/~lhf/ftp/lua/">lpack</ulink>
|
||||
by Luiz Henrique de Figueiredo.<indexterm><primary>Henrique de Figueiredo, Luiz</primary></indexterm>
|
||||
|
||||
The Binlib functions take a format string to encode and decode binary
|
||||
data. The operators of the format string are shown in <xref linkend="scripting-tbl-binlib" xrefstyle="select: label nopage"/>.</para>
|
||||
|
||||
<table id="scripting-tbl-binlib">
|
||||
<title>Binlib format string operators</title>
|
||||
<tgroup cols="2">
|
||||
<colspec colwidth="2*" />
|
||||
<colspec colwidth="5*" />
|
||||
<thead><row>
|
||||
<entry>Operator</entry>
|
||||
<entry>Description</entry>
|
||||
</row></thead>
|
||||
<tbody>
|
||||
<row><entry><literal>H</literal></entry><entry>hex string</entry></row>
|
||||
<row><entry><literal>B</literal></entry><entry>bit string</entry></row>
|
||||
<row><entry><literal>x</literal></entry><entry>null byte</entry></row>
|
||||
<row><entry><literal>z</literal></entry><entry>zero-terminated string</entry></row>
|
||||
<row><entry><literal>p</literal></entry><entry>string preceded by 1-byte integer length</entry></row>
|
||||
<row><entry><literal>P</literal></entry><entry>string preceded by 2-byte integer length</entry></row>
|
||||
<row><entry><literal>a</literal></entry><entry>string preceded by 4-byte integer length</entry></row>
|
||||
<row><entry><literal>A</literal></entry><entry>string</entry></row>
|
||||
<row><entry><literal>f</literal></entry><entry>float</entry></row>
|
||||
<row><entry><literal>d</literal></entry><entry>double</entry></row>
|
||||
<row><entry><literal>n</literal></entry><entry>Lua number</entry></row>
|
||||
<row><entry><literal>c</literal></entry><entry>char (1-byte integer)</entry></row>
|
||||
<row><entry><literal>C</literal></entry><entry>byte = unsigned char (1-byte unsigned integer)</entry></row>
|
||||
<row><entry><literal>s</literal></entry><entry>short (2-byte integer)</entry></row>
|
||||
<row><entry><literal>S</literal></entry><entry>unsigned short (2-byte unsigned integer)</entry></row>
|
||||
<row><entry><literal>i</literal></entry><entry>int (4-byte integer)</entry></row>
|
||||
<row><entry><literal>I</literal></entry><entry>unsigned int (4-byte unsigned integer)</entry></row>
|
||||
<row><entry><literal>l</literal></entry><entry>long (8-byte integer)</entry></row>
|
||||
<row><entry><literal>L</literal></entry><entry>unsigned long (8-byte unsigned integer)</entry></row>
|
||||
<row><entry><literal><</literal></entry><entry>little endian modifier</entry></row>
|
||||
<row><entry><literal>></literal></entry><entry>big endian modifier</entry></row>
|
||||
<row><entry><literal>=</literal></entry><entry>native endian modifier</entry></row>
|
||||
</tbody></tgroup></table>
|
||||
|
||||
<para>Note that the endian operators work as modifiers to all the characters following them in the format string.</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>bin.pack(fmt, p1, ...)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns a binary packed string. The format string describes how
|
||||
the parameters (p1, ...) will be interpreted. Numerical values following
|
||||
operators stand for operator repetitions and need an according amount of
|
||||
parameters. Operators expect appropriate parameter types.
|
||||
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bin.unpack(fmt, data, [init])</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns values read from the binary data string.
|
||||
First result is the position, at which unpack stopped. This can
|
||||
be used as init value for subsequent calls. The following results
|
||||
are the values according to the format string. Numerical values in
|
||||
the format string are interpreted as repetitions like in pack,
|
||||
except if used with A, B or H, in which cases the number tells unpack
|
||||
how many bytes to read.
|
||||
|
||||
Unpack stops if either the format string or the binary data string
|
||||
are exhausted.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="nse-pcre">
|
||||
<indexterm class="startofrange" id="nse-pcre-indexterm"><primary><varname>pcre</varname> NSE module</primary></indexterm>
|
||||
<indexterm><primary>Perl Compatible Regular Expressions (PCRE)</primary><secondary>in NSE</secondary></indexterm>
|
||||
@@ -1428,190 +1225,6 @@ if(s) code_to_be_done_on_match end
|
||||
<indexterm class="endofrange" startref="nse-openssl-indexterm"/>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="nse-lib-strbuf">
|
||||
<title>String Buffer Operations</title>
|
||||
<indexterm><primary><varname>strbuf</varname> NSE module</primary></indexterm>
|
||||
<para>
|
||||
Lua's string operations are very flexible and offer an easy-to-use way
|
||||
to manipulate strings. Concatenation using the <literal>..</literal>
|
||||
operator is such an operation. The drawback of the built-in API however is the way it handles
|
||||
concatenation of many string values. Since strings in Lua are
|
||||
immutable values, each time you concatenate two strings both get copied
|
||||
into the result string. The <literal>strbuf</literal> module offers a
|
||||
workaround for this problem, while maintaining the nice syntax. This
|
||||
is accomplished by overloading the concatenation operator (<literal>..</literal>) the equality operator (<literal>==</literal>) and the
|
||||
tostring operator. By overloading
|
||||
these operators, we reduce the overhead of using a string buffer instead
|
||||
of a plain string to wrap the first literal string assigned to a
|
||||
variable inside a <literal>strbuf.new()</literal> call. Afterwards you can append to the string buffer, or compare
|
||||
two string buffers for equality just as you would do with normal strings.
|
||||
When looking at the details there are some more restrictions/oddities:
|
||||
The concatenation operator requires its left-hand value to be a
|
||||
string buffer. Therefore, if you want to prepend a string to a given
|
||||
string buffer you have to create a new string buffer out of the string
|
||||
you want to prepend.
|
||||
The string buffer's <literal>tostring</literal> operator concatenates the
|
||||
strings inside the buffer using newlines by default, since this appears to
|
||||
be the separator used most often.
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>buffer = strbuf.new(...)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Creates a new string buffer. The optional arguments are added
|
||||
to the string buffer. Attempting to add non-strings will
|
||||
result in undefined behavior.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>buffer = strbuf.concat(strbuf1, value)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Concatenates the <literal>value</literal> (which has to be either
|
||||
a string or a string buffer) to <literal>strbuf1</literal>. This
|
||||
is also the function serving as the string buffer's concatenation operator.
|
||||
The above function call can thus also be expressed as:
|
||||
<literal>buffer = strbuf1 .. value</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>bool = strbuf.eqbuf(strbuf1, strbuf2)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Compares <literal>strbuf1</literal> and <literal>strbuf2</literal>
|
||||
for equality. For the function to return <literal>true</literal>, both values must be
|
||||
string buffers containing exactly the same strings. The <literal>eqbuf</literal> function is called to compare two strings for equality.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>strbuf.clear(strbuf)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Deletes all strings in <literal>strbuf</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>string = strbuf.dump(strbuf, "delimiter")</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Dumps <literal>strbuf</literal>'s contents as string. The second
|
||||
parameter is used as a delimiter between the strings stored inside
|
||||
<literal>strbuf</literal>. <literal>dump(strbuf, "\n")</literal> is
|
||||
used as the <literal>tostring</literal> function of string buffers.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect2>
|
||||
<sect2 id="nse-lib-url">
|
||||
<title>URL Manipulation Functions</title>
|
||||
<indexterm><primary><varname>url</varname> NSE module</primary></indexterm>
|
||||
|
||||
<para>URL manipulation functions have obvious uses. Fortunately
|
||||
there is already an implementation of URL generation functions
|
||||
inside the Lua <varname>socket</varname> package, which is fairly complete and
|
||||
<ulink
|
||||
url="http://www.cs.princeton.edu/~diego/professional/luasocket/old/luasocket-2.0-alpha/url.html">well
|
||||
documented</ulink>. For NSE, the <varname>url</varname> module was
|
||||
extended with two functions:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>table = url.parse_query("query-string")</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This function takes a <replaceable>query-string</replaceable> of the form <literal>name1=value1&name2=value2...</literal> and returns a table
|
||||
containing the name-value pairs, with the <literal>name</literal>
|
||||
as the key and the <literal>value</literal> as its associated value.
|
||||
The table corresponding to the above <replaceable>query-string</replaceable> would have two
|
||||
entries: <literal>table["name1"]="value1"</literal> and
|
||||
<literal>table["name2"]="value2"</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><option>query_string = url.build_query(table)</option>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is the inverse function to <literal>parse_query()</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="nse-lib-unpwdb">
|
||||
<title>Username/Password Database Functions</title>
|
||||
<indexterm><primary><varname>unpwdb</varname> NSE module</primary></indexterm>
|
||||
<para>
|
||||
The <literal>unpwdb</literal> module provides functions for easily obtaining
|
||||
usernames and/or passwords from a "database" (list). The most obvious use
|
||||
for this library is brute-force attack. The first two functions' return values
|
||||
are setup for use with exception handling via <literal>nmap.new_try()</literal>.
|
||||
<indexterm><primary>exceptions in NSE</primary></indexterm>
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>bool, response = unpwdb.usernames()</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This function returns a closure which returns a new username
|
||||
with every call, or <literal>nil</literal> when the list is
|
||||
exhausted. This closure takes an optional argument of
|
||||
<literal>"reset"</literal> to rewind the list to the beginning.
|
||||
You can specify your own username list with the script argument
|
||||
<literal>userdb</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>bool, response = unpwdb.passwords()</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This function returns a closure which returns a new password
|
||||
with every call, or <literal>nil</literal> when the list is
|
||||
exhausted. This closure takes an optional argument of
|
||||
<literal>"reset"</literal> to rewind the list to the beginning.
|
||||
You can specify your own password list with the script argument
|
||||
<literal>passdb</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>limit = unpwdb.timelimit()</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This function returns the suggested number of seconds to
|
||||
attempt a brute force attack, based on Nmap's timing values
|
||||
(<option>-T4</option>, etc) and whether or not a user-defined
|
||||
list is used. You can use the script argument
|
||||
<literal>notimelimit</literal> to make this function return
|
||||
<literal>nil</literal>, which means the brute-force should
|
||||
run until the list is empty. If <literal>notimelimit</literal>
|
||||
is not used, be sure to still check for <literal>nil</literal>
|
||||
return values on the above two functions in case you finish
|
||||
before the time limit is up.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<indexterm class="endofrange" startref="nse-library-indexterm"/>
|
||||
</sect1>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user