diff --git a/docs/scripting.xml b/docs/scripting.xml index 024db3c41..be6579577 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -312,11 +312,13 @@ $ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com} inside your script as local username= nmap.registry.args.user . As a general rule the subtables used to override options for scripts should be named as the script's - id, since otherwise scripts can't know where to - search for their arguments. + id, otherwise scripts won't know where to + retrieve their arguments. + The "since otherwise" segue was awkward, fixed. + Command-line Arguments @@ -451,6 +453,11 @@ categories. . The aggressive mode of Nmap implies the option . + + Calling -A the agressive mode is somewhat confusing. + You might call it "advanced/agressive" mode to differentiate it + from -T4. + @@ -593,8 +600,11 @@ that. Script Language + + Fixed the "more or less" to be less awkward. + - Nmap's scripting engine consists of three more or less distinct + Nmap's scripting engine is essentially three distinct parts. The largest part is the embeddable Lua interpreter. This is a lightweight language designed for extensibility. It offers a powerful and well documented API for interfacing with other @@ -610,16 +620,17 @@ that. exception handling mechanism. + I re-wrote this whole paragraph. + - Lua was designed with a small feature set to ease embedding. So - we have added extensions to support more specialized - functionality. These are basically - Lua modules written either in Lua itself, or in C. This - NSE library is the third part of the NSE. - - - - Lua Base Language + The third part of NSE is the NSE library. This library was + written to add special functionality and to augment the small + feature set of Lua. The NSE library is made up of Lua modules + written in either C, or Lua itself. + + + + Lua Base Language The Nmap scripting language is an embedded 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 + Wireshark and Second Life. + + I think including two examples like Wireshark and + Second Life should win over quite a few people. @@ -981,7 +997,7 @@ if(s) code_to_be_done_on_match end checks whether an IP address, provided as a string in dotted-quad notation, is part of the non-routed private IP address space, as described in RFC 1918. These addresses are the well known - 10.0.0.0/8,192.168.0.0/16 and + 10.0.0.0/8, 192.168.0.0/16 and 172.16.0.0/12 networks. @@ -1978,7 +1994,7 @@ nmap.fetchfile("nmap-rpc") - Target Information Retrieving by a Script + Target Information Retrieval by a Script Often the information passed to the script is not enough. Sometimes a script might want to correct target information or set it in the @@ -2065,6 +2081,9 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) 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. + The host and port arguments to this function should either be the tables passed to the action method or they should have @@ -2357,6 +2376,10 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) 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, @@ -2816,6 +2839,9 @@ 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? + @@ -3512,9 +3538,13 @@ passed to mainloop where the real work begins. Running Scripts + + Fixed up the intro sentance. + - Now to the actual script scanning, and the way NSE accomplishes - parallelization. Lua, through its concept of + Nmap is able to perform NSE script scanning in parallel by + making use of features of the Lua language. + Lua, through its concept of coroutines offers collaborative multi-threading, which means that scripts can suspend themselves, at defined points, and let other coroutines @@ -3571,15 +3601,22 @@ passed to mainloop where the real work begins. and put the dependencies inside the libtool commands in Makefile.in—here you should take a look at how pcre.so handles this. - So much for the way it should work. Now for some pitfalls we've - come across so far: These are results from building shared libraries in - general and not really specific to nselib. Linking with - static libraries (e.g. libnbase) sometimes leads - to problems with exporting symbols on some platforms (in our case - this was a x86_64-linux platform). To our knowledge no such + + + 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 + complications of building shared libraries and not nselib + itself. Linking with static libraries + (e.g. libnbase) sometimes leads to + problems with exporting symbols on some platforms (in our + case the x86_64-linux platform). To our knowledge no such problems occur when linking against already existing shared - libraries. - + libraries. + The Windows build system requires C module developers to create a MS Visual Studio Project file for their module