From d61e8114857a2c879c0481f53fc685ab8d5d19e5 Mon Sep 17 00:00:00 2001 From: fyodor Date: Thu, 19 Jun 2008 05:27:42 +0000 Subject: [PATCH] apply more suggestions from Brandon --- docs/scripting.xml | 144 +++++++++++++++++++-------------------------- 1 file changed, 61 insertions(+), 83 deletions(-) diff --git a/docs/scripting.xml b/docs/scripting.xml index 83e74fee7..e56cff859 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -318,8 +318,6 @@ $ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com} - The "since otherwise" segue was awkward, fixed. - Command-line Arguments @@ -454,14 +452,10 @@ categories. Another option which has effect on the scripting engine is - . The aggressive mode of Nmap implies + . The advance/aggressive mode of Nmap implies the option . - Calling -A the aggressive mode is somewhat confusing. - You might call it "advanced/aggressive" mode to differentiate it - from -T4. - @@ -605,8 +599,6 @@ that. Script Language - Fixed the "more or less" to be less awkward. - Nmap's scripting engine is essentially three distinct parts. The largest part is the embeddable Lua interpreter. This @@ -624,8 +616,6 @@ that. exception handling mechanism. - I re-wrote this whole paragraph. - 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. 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 Wireshark and Second Life. - I think including two examples like Wireshark and - Second Life should win over quite a few people. - @@ -2063,11 +2050,16 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) set_port_version - 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 + (version) was designed for this + purpose, as described in . + The set_port_version function is + used to record version information when it is + discovered. - The method takes a host and a port + 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"}) softmatched, nomatch, tcpwrapped, or - incomplete. - - A hard match will almost always be used, as it means - that the script was able to determine the protocol. - You can pass in nomatch 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. - - I don't understand what the opening sentence - in this paragraph is trying to say. + incomplete. + The hardmatched 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. 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"}) receive_lines() n is the minimum amount of characters we would like to receive. If more arrive, - we get all of them. If less than n characters arrive + we get all of them. If fewer than n 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"}) receive_buf - receive_buf tries to circumvent several - limitations in the other receive* functions. - receive_line(n), for example, tries to ensure that - there are at least n 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. - I didn't fully understand the previous - paragraph and I don't understand the next one. I - think they need more explanation or - clarification. - - receive_buf 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 - receive_buf. 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. + The receive_buf 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 receive_buf. This buffer is + cleared on subsequent calls to other Network I/O APY + functions. - receive_buf takes two arguments. - The first one is either a string or a function. If it is - a string it gets passed to Lua's string.find 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 string.find - (i.e. offsets of the start and the end of the delimiter inside the - buffer, or nil, if the delimiter is not found). + The receive_buf method takes + two arguments. The first one is either a string or + a function. Strings are passed to + Lua's string.find + function as the second (pattern) parameter, with the + buffer data being searched. If the + first receive_buf 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 string.find + (offsets to the start and the end of the delimiter + inside the buffer, or nil if the + delimiter is not found). The nselib + match.lua module (see + ) provides functions + for matching against regular expressions or byte + counts. These functions are suitable as arguments + to receive_buf. - The second argument is a boolean value which indicates whether the - delimiting pattern should be returned along with the received data or - discarded. + The second argument + to receive_buf 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 true is passed as the keeppatern argument. - A module inside the - nselib match.lua () provides - functions for matching received data against regular expressions or - for receiving a defined number of bytes. receive_buf's return values behave exactly as the return values of -the other receive* functions. Two values are returned (status,val)— -the first indicating whether the request was successful, the other -containing the returned data (or the case of a failure, an error message). + The return values of receive_buf are the same as the other receive* functions. A (status, val) tuple is returned. The status is true if the request was successful. The val variable contains the returned data, or an error message if the call failed. + + Possible error messages include those described previously for the other + receive* functions as well as the + following: - Possible error messages are those of the other - receive* functions and, in addition, the following: Error inside splitting-function—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. --> - How do scripts avoid race conditions when sharing - data in the registry? - @@ -3543,16 +3528,12 @@ passed to mainloop where the real work begins. Running Scripts - Fixed up the intro sentence. - 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, coroutines - 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 + 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 pcre.so handles this. - I split this paragraph into two parts and cleaned - up the second part. - Of course, theory and practice are rarely the same. Most of the trouble building nselib actually comes from the