diff --git a/docs/scripting.xml b/docs/scripting.xml index e5df50781..08b703013 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -2000,31 +2000,40 @@ categories = {"discovery", "external"} The version detection system built into Nmap was designed to efficiently recognize the vast majority of protocols with a simple - pattern matching syntax. Some protocols require a more complex - approach though, and a generalized scripting language is perfect for - this. + probe and pattern matching syntax. Some protocols require more + complex communication than version detection can handle. A + generalized scripting language as provided by NSE is perfect for + these tough cases. NSE's versionversion script category - category contains the scripts that enhance standard version + category contains scripts that enhance standard version detection. Scripts in this category are run whenever you request version detection with ; you don't need to use - to get version-detection scripts. (This cuts - the other way too: if you use you won't get + to run these. This cuts + the other way too: if you use , you won't get version scripts unless you also use - .) + . - This script detects version 2 of the Skype VoIP protocol, one which - is difficult to identify with version detection alone. If Skype gets - an HTTP GET request, it pretends to be an HTTP server and sends back - a 404. But for any other request it sends back a chunk of - random-looking data. Proper identification requires sending two - probes and comparing the two responses—an ideal task for NSE. + One protocol which we were unable to detect with normal version + detection is Skype version 2. The protocol was likely designed to + frustrate detection out of a fear that telecom-affiliated Internet + service providers might consider Skype competition and interfere + with the traffic. Yet we did find one way to detect it. If Skype + receives an HTTP GET request, it pretends to be a web server and + returns a 404 error. But for other requests, it sends back + a chunk of random-looking data. Proper identification requires + sending two probes and comparing the two responses—an ideal + task for NSE. The simple NSE script which accomplishes this is + shown in . + + A typical version detection script (Skype version 2 detection) description = [[ Detects the Skype version 2 service. @@ -2036,15 +2045,11 @@ categories = {"version"} require "comm" portrule = function(host, port) - if (port.number == 80 or - port.number == 443 or - port.service == nil or - port.service == "" or - port.service == "unknown") - and port.protocol == "tcp" - and port.state == "open" - and port.service ~= "http" - and port.service ~= "ssl/http" + if (port.number == 80 or port.number == 443 or + port.service == nil or port.service == "" or + port.service == "unknown") + and port.protocol == "tcp" and port.state == "open" + and port.service ~= "http" and port.service ~= "ssl/http" then return true else @@ -2084,51 +2089,49 @@ action = function(host, port) return end + If the script detects Skype, it augments its port table with now-known name and product fields. It then sends this new information to Nmap by calling - nmap.set_port_version(). Several other version + nmap.set_port_version. Several other version fields are available to be set if they are known, but in this case we only have the name and product. For the full list of version - fields refer to the documentation of - nmap.set_port_version(). + fields, refer to the nmap.set_port_version documentation. - Notice that if the script does not detect the protocol, it does - nothing. This is considered good practice; a script shouldn't + Notice that this script does nothing unless it detects the protocol. + A script shouldn't produce output (other than debug output) just to say it didn't learn anything. - Example Script + Example Script: <filename>finger.nse</filename> finger script The finger script (finger.nse) is a perfect - example of how short typical NSE scripts are. + example of a short and simple NSE script. - First the information fields are filled out. + First the information fields are assigned. A detailed description of what the script -actually does should go in the description field. +actually does goes in the description field. description = [[ Attempts to get a list of usernames via the finger service. ]]“description” script variable - author = "Eddie Bell <ejlbell@gmail.com>"Bell, Eddie“author” script variable - license = "Same as Nmap--See http://nmap.org/book/man-legal.html"“license” script variable The categories field is a table containing all the categories the script belongs to—These are used for -script selection through the option. +script selection with the option: categories = {"default", "discovery"} @@ -2136,7 +2139,7 @@ categories = {"default", "discovery"} You can use the facilities provided by the nselib () with require. Here -we want to use common communication functions and shorter port rules. +we want to use common communication functions and shorter port rules: require "comm" @@ -2147,25 +2150,16 @@ require "shortport" test whether it is using the well-known finger port (79/tcp), or whether the service is named finger based on version detection results or in the port number's listing -in nmap-services. - - -We want to check whether the service behind the port is finger, -or whether it runs on finger's well-known port 79. Through this we can -use the information gathered during the version scan (if finger runs -on a non-standard port) or still run against at least the port we -expect it, should the version detection information not be available. +in nmap-services: portrule = shortport.port_or_service(79, "finger")“portrule” script variable -First, the script uses nmap.new_try() to +First, the script uses nmap.new_try to create an exception handler that will quit the script in case of an -error. Next, it passes control to comm.exchange(), -which handles the network transaction. Here we have asked to receive no -more than around 100 lines, with a timeout of five seconds -(5000 ms). Any errors will be handled by the +error. Next, it passes control to comm.exchange, +which handles the network transaction. Here we have asked to wait in the communication exchange until we receive at least 100 lines, wait at least 5 seconds, or until the remote side closes the connection. Any errors are handled by the try exception handler. The script returns a string if the call to comm.exchange() was successful. @@ -2180,7 +2174,7 @@ end - Implementation + Implementation Details Nmap Scripting Engine (NSE)implementation Now how does all this work? The following section describes