From c03f225325d8dbf799fe25f854f3ca974a11853a Mon Sep 17 00:00:00 2001 From: david Date: Fri, 4 Jul 2008 01:23:01 +0000 Subject: [PATCH] Proofread docs/scripting.xml. Standardize on "PCRE" instead of various forms of "libpcre". --- docs/nmap-install.xml | 2 +- docs/scripting.xml | 74 +++++++++++++++++++++++-------------------- 2 files changed, 40 insertions(+), 36 deletions(-) diff --git a/docs/nmap-install.xml b/docs/nmap-install.xml index 8ed4511ba..f64de23ce 100644 --- a/docs/nmap-install.xml +++ b/docs/nmap-install.xml @@ -385,7 +385,7 @@ I would run ./configure --prefix=/home/fyodor directoryname -LibPCRE is a Perl-compatible regular expression library available from . Nmap normally looks for a copy on your system, and then fall back to its own copy if that fails. If your PCRE library is not in your compiler's standard search path, Nmap probably will not find it. In that case you can tell Nmap where it can be found by specifying the option to configure. Nmap then expects the library files to be in directoryname/lib and the include files to be in directoryname/include. In some cases, you may wish to use the PCRE libraries included with Nmap in preference to those already on your system. In that case, specify . +PCRE is a Perl-compatible regular expression library available from . Nmap normally looks for a copy on your system, and then fall back to its own copy if that fails. If your PCRE library is not in your compiler's standard search path, Nmap probably will not find it. In that case you can tell Nmap where it can be found by specifying the option to configure. Nmap then expects the library files to be in directoryname/lib and the include files to be in directoryname/include. In some cases, you may wish to use the PCRE libraries included with Nmap in preference to those already on your system. In that case, specify . directoryname Libdnet is an excellent networking library that Nmap uses for sending raw ethernet frames. The version in the Nmap tree is heavily modified (particularly the Windows code), so the default is to use that included version. If you wish to use a version already installed on your system instead, specify . Nmap then expects the library files to be in directoryname/lib and the include files to be in directoryname/include. diff --git a/docs/scripting.xml b/docs/scripting.xml index 12ab8773c..15b1db172 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -150,7 +150,7 @@ The reference manual is also and produce results below the port table. shows a typical script scan. Examples of service scripts producing output are Stealth SSH - Version, which tricks some SSH servers into divulging + version, which tricks some SSH servers into divulging version information without logging the attempt as they normally would, Service Owner, which connects to open ports, then performs a reverse-identd query to determine what @@ -217,7 +217,7 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds version, discovery, vuln, auth and default. - Categories are not case + Category names are not case sensitive. The following list describes each category. @@ -513,8 +513,8 @@ categories. Another option which has effect on the scripting engine is . - - The advance/aggressive mode of Nmap implies + features enabled by + The advanced/aggressive mode of Nmap implies the option . @@ -689,7 +689,7 @@ that. - The second part of the Nmap scripting engine is the NSE library, which + The second part of the Nmap Scripting Engine is the NSE library, which connects Lua and Nmap. This layer handles issues such as initialization of the Lua interpreter, scheduling of parallel script execution, script retrieval and @@ -986,7 +986,7 @@ that. interpreter, they are very different in syntax and not as powerful as standard regular expressions. So we have integrated Perl compatible regular expressions into Lua - using libPCRE and a modified version of the Lua PCRE library + using PCRE and a modified version of the Lua PCRE library written by Reuben Thomas Thomas, Reuben and Shmuel Zeigerman. @@ -994,21 +994,22 @@ that. These are the same sort of regular expressions used by Nmap version detection. The main modification to their library is that - the NSE version only supports PCRExpressions instead of both + the NSE version only supports PCRE expressions instead of both PCRE and POSIX patterns. In order to maintain a high script - execution speed, the library interfacing with libPCRE is + execution speed, the library interfacing with PCRE is kept very thin. It is not integrated as seamlessly as the Lua string pattern API. This allows script authors to decide - when to use PCRE expressions versus Lua patterns. PCRE + when to use PCRE expressions versus Lua patterns. The use of PCRE involves a separate pattern compilation step, which saves execution time when patterns are reused. Compiled patterns can be cached in the NSE registry and reused by other scripts. The PCRE functions reside inside the pcre + pcre NSE module namespace. Perl Compatible Regular Expressions (PCRE)security vulnerabilities in - LibPCRE has a history of security vulnerabilities + PCRE has a history of security vulnerabilities allowing attackers who are able to compile arbitrary regular expressions to execute arbitrary code. More such vulnerabilities may be discovered in the future. These have @@ -1503,10 +1504,10 @@ if(s) code_to_be_done_on_match end URL manipulation functions have obvious uses. Fortunately there is already an implementation of URL generation functions - inside the Lua-socket package, which is fairly complete and + inside the Lua socket package, which is fairly complete and well - documented. For NSE, Lua-socket's URL module was + documented. For NSE, the url module was extended with two functions: @@ -1621,8 +1622,8 @@ if(s) code_to_be_done_on_match end table like the host table passed by nmap. The second argument is either the port number or a table like the port table passed by nmap. SSL is used for the request if either port.service - equals "https" or port.version.service_tunnel - equals "ssl". The third argument is the request. The fourth + equals https or port.version.service_tunnel + equals ssl. The third argument is the request. The fourth argument is a table for further options. You can specify a timeout for the socket operations with the timeout key. @@ -1990,7 +1991,9 @@ if(s) code_to_be_done_on_match end - A string containing the interface name (dnet-style) through + A string containing the interface name (dnet-style) + libdnet + through which packets to the host are sent. @@ -2387,6 +2390,7 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) For the provided dnet-style + libdnet interface_name, nmap.get_interface_link() returns what kind of link level hardware the interface @@ -2408,7 +2412,7 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) To allow for efficient and parallelizable network I/O, NSE provides an interface to Nsock, the Nmap socket library. The smart callback mechanism Nsock uses is fully transparent to - NSE scripts. The main benefit of Nmap-NSE sockets is that they + NSE scripts. The main benefit of NSE's sockets is that they never block on I/O operations, allowing many scripts to be run in parallel. The I/O parallelism is fully transparent to authors of NSE scripts. In NSE you can either program as if you were using a single non @@ -2436,7 +2440,7 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) The new_socket() Nmap call returns an - Nmap-NSE socket object which is the recommended method for network + NSE socket object which is the recommended method for network I/O. It provides facilities to perform communication using the UDP, TCP and SSL protocol in a uniform manner. @@ -2450,13 +2454,13 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) - The connect method of Nmap-NSE socket objects will put + The connect method of NSE socket objects will put the socket in a state ready for communication. It takes as arguments a host descriptor (either an IP address or a host name), a port number and optionally a protocol. The protocol must be one of - "tcp", "udp" or - "ssl". By default the connect call + tcp, udp or + ssl. By default the connect call will attempt to open a TCP connection. On success the returned value of status is true. If the connection attempt has @@ -2802,7 +2806,7 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) device—the dnet-style interface name of the device you want to capture from. snaplen—defines the length of each packet you want to capture (similar to the option to tcpdump) promisc—should be set to 1 if the interface should activate promiscuous mode, and zero otherwise. -test_function—callback function used to compute the packet-hash +test_function—callback function used to compute the packet hash bpf—a string describing a Berkeley packet filter expression (like those provided to tcpdump) @@ -3370,7 +3374,7 @@ end efficiently recognize the vast majority of protocols with a simple pattern matching syntax. Some protocols require a more complex approach, and a generalized scripting language is - perfect for this. Skype2 is one such protocol. It pretends to + perfect for this. Skype v2 is one such protocol. It pretends to be an http server, requiring multiple queries to determine its true nature. NSE has been integrated into Nmap's version detection framework to handle these cases. The scripts which @@ -3524,7 +3528,7 @@ categories = {"discovery"} You can use the facilities provided by the nselib () by requiring them. Here +linkend="nse-library"/>) with require. Here we want to use shorter port rules. @@ -3610,7 +3614,7 @@ end Service owner script auth service showOwner.nse demonstrates the flexibility - of the NSE, which is unmatched by other parts of Nmap. If the target + of NSE, which is unmatched by other parts of Nmap. If the target is running an identd daemon it connects to it for each running service and tries to identify its owner. @@ -3663,7 +3667,7 @@ action = function(host, port) local owner = "" -Scripts can open any number of connection they want. +Scripts may open any number of connections. local client_ident = nmap.new_socket() @@ -3707,7 +3711,7 @@ end Nmap Scripting Engine (NSE)implementation Now how does all this work? The following section describes - some interesting aspects of the NSE. While the focus primarily lies on + some interesting aspects of NSE. While the focus primarily lies on giving script writers a better feeling of what happens with scripts, it should also provide a starting point for understanding (and extending) the NSE sources. @@ -3769,7 +3773,7 @@ end The debug library (namespace: debug)—The debug library provides you with a somewhat lower level API - to the Lua-interpreter. Through it you can access functions along + to the Lua interpreter. Through it you can access functions along the execution stack, get function closures and object metatables, etc. @@ -3778,7 +3782,7 @@ end In addition to loading the libraries provided with Lua, the functions in the nmap namespace are also loaded. The search -path for modules is set to the default one prepended by the nselib +path for modules is set to the default one prepended by the nselib directory (which is searched in the locations Nmap searches for its data files and scripts). In this step the provided script arguments also get stored inside the registry. @@ -3838,7 +3842,7 @@ ports. Therefore it is advisable to leave the rules as simple as possible and to do all the computation inside the action, as a script will only be executed if it is run against a specific target. After the check those script-target combinations -get their own Lua-thread. A +get their own Lua thread. A thread running against a host will have only a hostrule passed to the action closure whereas a thread running against a port will have both a hostrule and portrule passed. Each thread is stored with information relevant to the thread. This information @@ -3892,12 +3896,12 @@ The mainloop function will work on each runlevel grouping of threads in order. Basically C modules consist of the functions they provide to Lua, which have to be of type lua_CFunction. Additionally they have to contain a function which is used to actually open the module. By convention these function names are luaopen_modulename. - A good starting point for writing such modules is provided with + A good starting point for writing such modules is provided by bit.c - bite NSE module - and pcre.c inside - the nselib/ subdirectory of Nmap's source tree, - which are two C modules already provided by the nselib. C modules + bit NSE module + inside + the nselib/ subdirectory of Nmap's source tree. + bit is a C module already provided by the nselib. C modules basically are shared libraries which get loaded at runtime by Lua. @@ -3945,7 +3949,7 @@ The mainloop function will work on each runlevel grouping of threads in order. Nmap's Visual Studio solution file (mswin32\nmap.sln) and make sure that nse_bitlib.vcproj depends on your project, - because it is there nselib-modules get copied to their final destinations and are included in Nmap. + because it is there that nselib modules get copied to their final destinations and are included in Nmap.