PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2025-12-12 02:39:03 +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

140
docs/scripting.xml
View File

@@ -318,8 +318,6 @@ $ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com}
</para> </para>
</sect2> </sect2>
<comment>The "since otherwise" segue was awkward, fixed.</comment>
<sect2 id="nse-cmd-line-args"> <sect2 id="nse-cmd-line-args">
<title>Command-line Arguments</title> <title>Command-line Arguments</title>
<para> <para>
@@ -454,14 +452,10 @@ categories.</para>
</para> </para>
<para> <para>
Another option which has effect on the scripting engine is 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>. the option <option>-sC</option>.
</para> </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>
</para> </para>
</sect2> </sect2>
@@ -605,8 +599,6 @@ that.</para>
<sect1 id="nse-language"> <sect1 id="nse-language">
<title>Script Language</title> <title>Script Language</title>
<comment>Fixed the "more or less" to be less awkward.</comment>
<para> <para>
Nmap's scripting engine is essentially three distinct Nmap's scripting engine is essentially three distinct
parts. The largest part is the embeddable Lua interpreter. This parts. The largest part is the embeddable Lua interpreter. This
@@ -624,8 +616,6 @@ that.</para>
exception handling mechanism. exception handling mechanism.
</para> </para>
<comment>I re-wrote this whole paragraph.</comment>
<para> <para>
The third part of NSE is the NSE library. This library was The third part of NSE is the NSE library. This library was
written to add special functionality and to augment the small written to add special functionality and to augment the small
@@ -673,12 +663,9 @@ that.</para>
execution, was designed with embeddability in mind, has execution, was designed with embeddability in mind, has
excellent documentation, and is actively developed by a large excellent documentation, and is actively developed by a large
and committed community. 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>. <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> </para>
</sect2> </sect2>
</sect1> </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> <indexterm><primary>set_port_version</primary></indexterm></term>
<listitem> <listitem>
<para> <para>
To provide a flexible extension to Nmap's version NSE scripts are sometimes able to determine the
detection NSE scripts can set the version and service service name and application version listening on a
variables of a port. 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 table as arguments. The third argument describes the
state in which the script completed. It is a string state in which the script completed. It is a string
which is one of: which is one of:
@@ -2076,17 +2068,11 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})
<literal>nomatch</literal>, <literal>nomatch</literal>,
<literal>tcpwrapped</literal>, or <literal>tcpwrapped</literal>, or
<literal>incomplete</literal>. <literal>incomplete</literal>.
The <literal>hardmatched</literal> argument is almost
A hard match will almost always be used, as it means always used, as it signifies a successful match. The
that the script was able to determine the protocol. other possible states are generally only used for
You can pass in <literal>nomatch</literal> if the standard version detection rather than the NSE
script fails to match the target port, but it is enhancement.</para>
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>
<para>The host and port arguments to this function <para>The host and port arguments to this function
should either be the tables passed to the 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> <literal>receive_lines()</literal>
<replaceable>n</replaceable> is the minimum amount of <replaceable>n</replaceable> is the minimum amount of
characters we would like to receive. If more arrive, 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. before the operation times out, a TIMEOUT error occurs.
Other error conditions are the same as for the send operation. 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> <indexterm><primary>receive_buf</primary></indexterm></term>
<listitem> <listitem>
<para> <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 The <literal>receive_buf</literal> method reads data
paragraph and I don't understand the next one. I from the network until it encounters the given delimiter
think they need more explanation or string (or matches the function passsed in). Only data
clarification.</comment> 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> on the other hand returns only the <para>The <literal>receive_buf</literal> method takes
part of the received data until the first match of a delimiter, two arguments. The first one is either a string or
with the rest being saved inside a buffer for later calls to a function. Strings are passed to
<literal>receive_buf</literal>. This buffer gets cleared on calls to Lua's <literal><ulink role="hidepdf"
other functions inside the Network I/O API. Should the data not url="http://www.lua.org/manual/5.1/manual.html#5.4">string.find</ulink></literal>
contain the delimiter another read request is sent and the buffer is function as the second (pattern) parameter, with the
checked again when more data is present.</para> 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><literal>receive_buf</literal> takes two arguments. <para>The second argument
The first one is either a string or a function. If it is to <literal>receive_buf</literal> is a boolean value
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 which indicates whether the delimiting pattern
parameter, with the buffer data being searched. If it is a function should be returned along with the received data or
it is expected to take exactly one parameter (the buffer) and its discarded. The delimiter is included if <literal>true</literal> is passed as the <literal>keeppatern</literal> argument.</para>
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 second argument is a boolean value which indicates whether the <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>
delimiting pattern should be returned along with the received data or
discarded.</para>
<para>A module inside the <para>Possible error messages include those described previously for the other
nselib <literal>match.lua</literal> (<xref linkend="nse-lib-match"/>) provides <literal>receive*</literal> functions as well as the
functions for matching received data against regular expressions or following:
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>Possible error messages are those of the other
<literal>receive*</literal> functions and, in addition, the following:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><quote>Error inside splitting-function</quote>&mdash;if the first argument was <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 expression in the registry so that scripts which need the same
pattern do not have to recompile it. --> pattern do not have to recompile it. -->
<comment>How do scripts avoid race conditions when sharing
data in the registry?</comment>
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
@@ -3543,16 +3528,12 @@ passed to mainloop where the real work begins.
<sect2 id="nse-implementation-run"> <sect2 id="nse-implementation-run">
<title>Running Scripts</title> <title>Running Scripts</title>
<comment>Fixed up the intro sentence.</comment>
<para> <para>
Nmap is able to perform NSE script scanning in parallel by Nmap is able to perform NSE script scanning in parallel by
making use of features of the Lua language. making use of Lua language features. In particular,
Lua, through its concept of
<ulink url="http://www.lua.org/manual/5.1/manual.html#2.11">coroutines <ulink url="http://www.lua.org/manual/5.1/manual.html#2.11">coroutines
</ulink> offers collaborative multi-threading, which means that scripts </ulink> offer collaborative multi-threading so scripts can suspend themselves at defined points, and allow other coroutines
can suspend themselves, at defined points, and let other coroutines to execute. Since network I/O, especially waiting for responses from
execute. Since network I/O, especially waiting for responses from
remote host, is the part of scripts which would consume most time with remote host, is the part of scripts which would consume most time with
waiting, this is the point where scripts suspend themselves and let waiting, this is the point where scripts suspend themselves and let
others execute. Each call to some of the functions of the Nsock wrapper 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. take a look at how <literal>pcre.so</literal> handles this.
</para> </para>
<comment>I split this paragraph into two parts and cleaned
up the second part.</comment>
<para> <para>
Of course, theory and practice are rarely the same. Most of Of course, theory and practice are rarely the same. Most of
the trouble building nselib actually comes from the the trouble building nselib actually comes from the