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

apply more suggestions from Brandon

Browse Source
This commit is contained in:
fyodor
2008-06-19 05:27:42 +00:00
parent ee8afa1b12
commit d61e811485
1 changed files with 61 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/scripting.xml
View File

@@ -318,8 +318,6 @@ $ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com}
</para>
</sect2>
<comment>The "since otherwise" segue was awkward, fixed.</comment>
<sect2 id="nse-cmd-line-args">
<title>Command-line Arguments</title>
<para>
@@ -454,14 +452,10 @@ categories.</para>
</para>
<para>
Another option which has effect on the scripting engine is
<option>-A</option>. The aggressive mode of Nmap implies
<option>-A</option>. The advance/aggressive mode of Nmap implies
the option <option>-sC</option>.
</para>
<comment>Calling -A the aggressive mode is somewhat confusing.
You might call it "advanced/aggressive" mode to differentiate it
from -T4.</comment>
<para>
</para>
</sect2>
@@ -605,8 +599,6 @@ that.</para>
<sect1 id="nse-language">
<title>Script Language</title>
<comment>Fixed the "more or less" to be less awkward.</comment>
<para>
Nmap's scripting engine is essentially three distinct
parts. The largest part is the embeddable Lua interpreter. This
@@ -624,8 +616,6 @@ that.</para>
exception handling mechanism.
</para>
<comment>I re-wrote this whole paragraph.</comment>
<para>
The third part of NSE is the NSE library. This library was
written to add special functionality and to augment the small
@@ -673,12 +663,9 @@ that.</para>
execution, was designed with embeddability in mind, has
excellent documentation, and is actively developed by a large
and committed community.
Lua is even embedded in popular applications like
Lua is even embedded in popular applications including
<application>Wireshark</application> and <application>Second Life</application>.
<comment>I think including two examples like Wireshark and
Second Life should win over quite a few people.</comment>
</para>
</sect2>
</sect1>
@@ -2063,11 +2050,16 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
<indexterm><primary>set_port_version</primary></indexterm></term>
<listitem>
<para>
To provide a flexible extension to Nmap's version
detection NSE scripts can set the version and service
variables of a port.
NSE scripts are sometimes able to determine the
service name and application version listening on a
port. A whole script category
(<literal>version</literal>) was designed for this
purpose, as described in <xref linkend="nse-vscan"/>.
The <literal>set_port_version</literal> function is
used to record version information when it is
discovered.</para>
The method takes a host and a port
<para>This method takes a host and a port
table as arguments. The third argument describes the
state in which the script completed. It is a string
which is one of:
@@ -2075,18 +2067,12 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
<literal>softmatched</literal>,
<literal>nomatch</literal>,
<literal>tcpwrapped</literal>, or
<literal>incomplete</literal>.
A hard match will almost always be used, as it means
that the script was able to determine the protocol.
You can pass in <literal>nomatch</literal> if the
script fails to match the target port, but it is
probably already set that way anyway. One of the
other states should only be used if you know exactly
what you are doing.</para>
<comment>I don't understand what the opening sentence
in this paragraph is trying to say.</comment>
<literal>incomplete</literal>.
The <literal>hardmatched</literal> argument is almost
always used, as it signifies a successful match. The
other possible states are generally only used for
standard version detection rather than the NSE
enhancement.</para>
<para>The host and port arguments to this function
should either be the tables passed to the
@@ -2360,7 +2346,7 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
<literal>receive_lines()</literal>
<replaceable>n</replaceable> is the minimum amount of
characters we would like to receive. If more arrive,
we get all of them. If less than <replaceable>n</replaceable> characters arrive
we get all of them. If fewer than <replaceable>n</replaceable> characters arrive
before the operation times out, a TIMEOUT error occurs.
Other error conditions are the same as for the send operation.
@@ -2373,49 +2359,51 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
<indexterm><primary>receive_buf</primary></indexterm></term>
<listitem>
<para>
<literal>receive_buf</literal> tries to circumvent several
limitations in the other <literal>receive*</literal> functions.
<literal>receive_line(n)</literal>, for example, tries to ensure that
there are at least <replaceable>n</replaceable> lines received and returns everything it has
already read from the connection (even though there may be much more
data than requested). It also leaves line-parsing to the user.</para>
<comment>I didn't fully understand the previous
paragraph and I don't understand the next one. I
think they need more explanation or
clarification.</comment>
<para><literal>receive_buf</literal> on the other hand returns only the
part of the received data until the first match of a delimiter,
with the rest being saved inside a buffer for later calls to
<literal>receive_buf</literal>. This buffer gets cleared on calls to
other functions inside the Network I/O API. Should the data not
contain the delimiter another read request is sent and the buffer is
checked again when more data is present.</para>
The <literal>receive_buf</literal> method reads data
from the network until it encounters the given delimiter
string (or matches the function passsed in). Only data
which occurs before the delimiter is returned, and the
delimiter is then erased. This function continues to
read from the network until the delimiter is found or
the function times out. If data is read beyond the
delimiter, that data is saved in a buffer for the next
call to <literal>receive_buf</literal>. This buffer is
cleared on subsequent calls to other Network I/O APY
functions.</para>
<para><literal>receive_buf</literal> takes two arguments.
The first one is either a string or a function. If it is
a string it gets passed to Lua's <literal><ulink role="hidepdf" url="http://www.lua.org/manual/5.1/manual.html#5.4">string.find</ulink></literal> function as the (second) pattern
parameter, with the buffer data being searched. If it is a function
it is expected to take exactly one parameter (the buffer) and its
return values have to be like those of <literal>string.find</literal>
(i.e. offsets of the start and the end of the delimiter inside the
buffer, or <literal>nil</literal>, if the delimiter is not found).</para>
<para>The <literal>receive_buf</literal> method takes
two arguments. The first one is either a string or
a function. Strings are passed to
Lua's <literal><ulink role="hidepdf"
url="http://www.lua.org/manual/5.1/manual.html#5.4">string.find</ulink></literal>
function as the second (pattern) parameter, with the
buffer data being searched. If the
first <literal>receive_buf</literal> argument is a
function, it is expected to take exactly one
parameter (the buffer) and its return values must be
in the same format as <literal>string.find</literal>
(offsets to the start and the end of the delimiter
inside the buffer, or <literal>nil</literal> if the
delimiter is not found). The nselib
<literal>match.lua</literal> module (see
<xref linkend="nse-lib-match"/>) provides functions
for matching against regular expressions or byte
counts. These functions are suitable as arguments
to <literal>receive_buf</literal>.</para>
<para>The second argument is a boolean value which indicates whether the
delimiting pattern should be returned along with the received data or
discarded.</para>
<para>The second argument
to <literal>receive_buf</literal> is a boolean value
which indicates whether the delimiting pattern
should be returned along with the received data or
discarded. The delimiter is included if <literal>true</literal> is passed as the <literal>keeppatern</literal> argument.</para>
<para>A module inside the
nselib <literal>match.lua</literal> (<xref linkend="nse-lib-match"/>) provides
functions for matching received data against regular expressions or
for receiving a defined number of bytes. <literal>receive_buf</literal>'s return values behave exactly as the return values of
the other <literal>receive*</literal> functions. Two values are returned (status,val)&mdash;
the first indicating whether the request was successful, the other
containing the returned data (or the case of a failure, an error message).</para>
<para>The return values of <literal>receive_buf</literal> are the same as the other <literal>receive*</literal> functions. A <literal>(status, val)</literal> tuple is returned. The <literal>status</literal> is <literal>true</literal> if the request was successful. The <literal>val</literal> variable contains the returned data, or an error message if the call failed.</para>
<para>Possible error messages include those described previously for the other
<literal>receive*</literal> functions as well as the
following:
<para>Possible error messages are those of the other
<literal>receive*</literal> functions and, in addition, the following:
<itemizedlist>
<listitem>
<para><quote>Error inside splitting-function</quote>&mdash;if the first argument was
@@ -2843,9 +2831,6 @@ try(socket:send(result))
expression in the registry so that scripts which need the same
pattern do not have to recompile it. -->
<comment>How do scripts avoid race conditions when sharing
data in the registry?</comment>
</para>
</sect2>
</sect1>
@@ -3543,16 +3528,12 @@ passed to mainloop where the real work begins.
<sect2 id="nse-implementation-run">
<title>Running Scripts</title>
<comment>Fixed up the intro sentence.</comment>
<para>
Nmap is able to perform NSE script scanning in parallel by
making use of features of the Lua language.
Lua, through its concept of
making use of Lua language features. In particular,
<ulink url="http://www.lua.org/manual/5.1/manual.html#2.11">coroutines
</ulink> offers collaborative multi-threading, which means that scripts
can suspend themselves, at defined points, and let other coroutines
execute. Since network I/O, especially waiting for responses from
</ulink> offer collaborative multi-threading so scripts can suspend themselves at defined points, and allow other coroutines
to execute. Since network I/O, especially waiting for responses from
remote host, is the part of scripts which would consume most time with
waiting, this is the point where scripts suspend themselves and let
others execute. Each call to some of the functions of the Nsock wrapper
@@ -3607,9 +3588,6 @@ passed to mainloop where the real work begins.
take a look at how <literal>pcre.so</literal> handles this.
</para>
<comment>I split this paragraph into two parts and cleaned
up the second part.</comment>
<para>
Of course, theory and practice are rarely the same. Most of
the trouble building nselib actually comes from the