diff --git a/docs/nmap-install.xml b/docs/nmap-install.xml index f838cdd54..c304d25a6 100644 --- a/docs/nmap-install.xml +++ b/docs/nmap-install.xml @@ -21,8 +21,8 @@ have it. Many free operating system distributions (including most Linux and BSD systems) come with Nmap, although it may not be installed by default. On Unix systems, open a terminal window and try executing the command nmap . -If Nmap exists and is in your PATH, -PATH environment variable +If Nmap exists and is in your +PATH,PATH environment variable you should see output similar to . version number of Nmap @@ -47,13 +47,11 @@ version number (here 4.65). Even if your system already has a copy of Nmap, you should consider upgrading to the latest version available from . -downloading +url="http://nmap.org/download.html" />.downloading Newer versions often run faster, fix important bugs, and feature updated operating system and service version detection databases. A list of changes since the version already on your system can be found -at . -changelog +at .changelog Nmap output examples in this book may not match the output produced by older versions. @@ -134,10 +132,10 @@ forge and properly sign a trojan release. While numerous applications are able to verify PGP signatures, I recommend the GNU Privacy Guard (GPG). - keys, cryptographic -Nmap releases are signed with a special Nmap Project Signing Key, -Nmap Project Signing Key + +Nmap releases are signed with a special +Nmap Project Signing Key,Nmap Project Signing Key which can be obtained from they major keyservers or . My key is included in that file too. The keys can be imported with the command @@ -197,9 +195,8 @@ gpg: BAD signature from While PGP signatures are the recommended validation technique, -SHA1 and MD5 (among other) hashes -hashes, cryptographic -digests, cryptographic +SHA1 and MD5 (among other) +hasheshashes, cryptographicdigests, cryptographic are made available for more casual validation. An attacker who can manipulate your Internet traffic in real time (and is extremely skilled) or who compromises Nmap.Org @@ -286,8 +283,9 @@ url="http://cgi.insecure.org/mailman/listinfo/nmap-svn"/>. Unix Compilation and Installation from Source Code -Unixinstalling on -installationfrom source +Unix, installing on +Linux, compiling on +installationfrom source code source code compilation @@ -378,7 +376,7 @@ I would run ./configure --prefix=/home/fyodorZenmapdisablingThis option prevents the Zenmap graphical frontend from being installed. Normally the build system checks your system for requirements such as the Python scripting language and then installs Zenmap if they are all available. directoryname -OpenSSLdisablingThe version detection subsystem of Nmap is able to probe SSL-encrypted services using the free OpenSSL libraries. Normally the Nmap build system looks for these libraries on your system and include this capability if they are found. If they are in a location your compiler does not search for by default, but you still want them to be used, specify . Nmap then looks in directoryname/libs for the OpenSSL libraries themselves and directoryname/include for the necessary header files. Specify to disable SSL entirely. +OpenSSLdisablingThe version detection subsystem of Nmap is able to probe SSL-encrypted services using the free OpenSSL libraries. Normally the Nmap build system looks for these libraries on your system and include this capability if they are found. If they are in a location your compiler does not search for by default, but you still want them to be used, specify . Nmap then looks in directoryname/libs for the OpenSSL libraries themselves and directoryname/include for the necessary header files. Specify to disable SSL entirely. directoryname Nmap uses the Libpcap library for capturing raw IP packets. Nmap normally looks for an existing copy of Libpcap on your system and uses that if the version number and platform is appropriate. Otherwise Nmap includes its own recent copy of Libpcap, which has been modified for improved Linux functionality. The specific changes are described in libpcap/NMAP_MODIFICATIONS in the Nmap source directory. Because of these Linux-related changes, Nmap always uses its own Libpcap by default on that platform. If you wish to force Nmap to link with your own Libpcap, pass the option to configure. Nmap then expects the Libpcap library to be in directoryname/lib/libpcap.a and the include files to be in directoryname/include. Nmap will always use the version of Libpcap included in its tarball if you specify . @@ -415,14 +413,13 @@ If you make code changes to fix the problem, please send a patch (created with diff -uw oldfile newfile) and any details about your problem and platform to me at fyodor@insecure.org. Integrating the change into the base Nmap distribution allows many other users to benefit, and prevents you from having to make the changes with each new Nmap version. Ask Google and other Internet resources -Try searching for the exact error message on Google or other search engines. You might also want to browse recent activity on the Nmap development (nmap-dev) -nmap-dev mailing list +Try searching for the exact error message on Google or other search engines. You might also want to browse recent activity on the Nmap development +(nmap-dev)nmap-dev mailing list list—archives are available at . Ask nmap-dev If none of your research has led to a solution for your problem, try sending a report to the Nmap development (nmap-dev) -nmap-dev mailing list list. If you subscribe first, your message gets through faster because it does not go through moderation. Subscribe by sending a blank email to @@ -448,10 +445,8 @@ packages. Linux Distributions -Linuxinstalling on -Linuxpopularity as Nmap platform Linux is far and away the most popular platform for running Nmap. In one user survey, 86% said that Linux was at least one of the platforms on which they run @@ -474,6 +469,7 @@ the most common distributions. RPM-based Distributions (Red Hat, Mandrake, Suse, Fedora) RPM +Linuxinstalling on, with RPM> Red Hat (Linux distribtion)installing on, with RPM> Mandrake (Linux distribution)installing on, with RPM Suse (Linux distribution)installing on, with RPM @@ -536,6 +532,7 @@ reason there are no Zenmap source RPMs. Updating Red Hat, Fedora, Mandrake, and Yellow Dog Linux with Yum Yum +Linuxinstalling on, with Yum Red Hat (Linux distribtion)installing on, with Yum Mandrake (Linux distribution)installing on, with Yum Yellow Dog (Linux distribution)installing on, with Yum @@ -609,8 +606,9 @@ Complete! Debian Linux and Derivatives such as Ubuntu -Debianinstalling on -Ubuntuinstalling on +Linuxinstalling on, with apt-get +Debian, installing on +Ubuntu, installing on LaMont Jones Jones, LaMont does a fabulous job maintaining the Nmap .deb @@ -635,14 +633,12 @@ described in . Windows -Windows +Windows Microsoft WindowsWindows While Nmap was once a Unix-only tool, a Windows version was released in 2000 and has since become the second most popular Nmap -platform (behind Linux). -Windowspopularity as Nmap platform -Because of this popularity and the fact that +platform (behind Linux). Because of this popularity and the fact that many Windows users do not have a compiler, binary executables are distributed for each major Nmap release. While it has improved dramatically, the Windows port is not quite as efficient or stable as @@ -693,8 +689,6 @@ the CurrentControlSet\Services\Tcpip\Parameters entry under < years, Nmap was a Unix-only tool, and it would likely still be that way if not for their efforts. -Windowsinstalling on - Windows users have three choices for installing Nmap, all of which are available from the download page at . @@ -702,7 +696,7 @@ download page at . Windows Self-installer -Windowsself-installer +Windowsself-installer Every major “stable” Nmap release comes with Windows self-installer named @@ -720,7 +714,7 @@ command-line. Command-line Zip Binaries -Windowszip binaries +Windowszip binaries Most users prefer installing Nmap with the self-installer discussed previously. @@ -729,8 +723,8 @@ command-line binaries and associated files in a Zip archive. No graphical interface is included, so you need to run nmap.exe from a DOS/command window. Or you can download and install a superior command shell such as those included -with the free Cygwin -Cygwin +with the free +CygwinCygwin system available from . Here are the step-by-step instructions for installing and executing the Nmap .zip binaries. Installing the Nmap zip binaries @@ -769,7 +763,7 @@ WinPcap requirement. Compile from Source Code -Windowscompilation on +Windowscompiling on Most Windows users prefer to use the Nmap binary self-installer, @@ -804,6 +798,7 @@ Cygwin. Executing Nmap on Windows +Windowsrunning Nmap on Nmap releases now include the Zenmap graphical user interface for Nmap. If @@ -815,8 +810,8 @@ detailed instructions for users who are unfamiliar with command-line interfaces: -Make sure the user you are logged in as has administrative privileges -privileged users +Make sure the user you are logged in as has +administrative privilegesprivileged users on the computer (user should be a member of the administrators group). Open a command/DOS Window. Though it can be found in the program menu tree, the simplest approach is to choose Start @@ -859,8 +854,9 @@ Computer and then click properties.< Click the Environment Variables button. - + PATH environment variablePath on Windows + Choose Path from the System variables section, then hit edit. @@ -874,16 +870,17 @@ command such as nmap scanme.nmap.org from any directory. + Sun Solaris -Solaris +Solaris, installing on Sun SolarisSolaris Solaris has long been well-supported by Nmap. Sun even donated a complete SPARCstation to the project, which is still being used to test new Nmap builds. For this reason, many Solaris users compile and install from source code as described in . Users who prefer native Solaris packages will be pleased to -learn that Steven Christensen -Christensen, Steven +learn that +Steven ChristensenChristensen, Steven does an excellent job of maintaining Nmap packages over at . Instructions are on his site, and are generally very simple: download the @@ -898,7 +895,7 @@ you have more flexibility in the build process. Apple Mac OS X -Mac OS Xinstalling on +Mac OS X Apple Mac OS XMac OS X Thanks to several people graciously donating shell accounts on @@ -918,9 +915,8 @@ the installer. In the the Nmap download page there is a file called nmap-version.dmg, where version is the version number of the most -recent release. The .dmg -.dmg (Mac OS X disk image) -disk image (Mac OS X) +recent release. The +.dmg.dmg (Mac OS X disk image)disk image (Mac OS X) file is known as a disk image. This is the process for installing from the disk image. @@ -951,7 +947,7 @@ have to compile from source or use a third-party package. -Mac OS Xcompilation on +Mac OS Xcompiling on Compile from Source Code Compiling Nmap from source on Mac OS X is no more difficult than @@ -961,8 +957,7 @@ on other platforms once a proper build environment is in place. Compile Nmap from source code Compiling Nmap on Mac OS X requires -Xcode, -Xcode +Xcode,Xcode Apple's developer tools that include GCC and the rest of the usual build system. Xcode is not installed by default but it is available as an optional install on the Mac OS X installation discs. If you do not have @@ -971,8 +966,7 @@ Xcode free of charge by following these steps. Apple restricts downloads of Xcode to members of the -Apple Developer Connection. -Apple Developer Connection +Apple Developer Connection.Apple Developer Connection Browse to and fill out some forms to create an account. Skip to the next step if you already have an @@ -1006,6 +1000,7 @@ install Zenmap as usual. +Mac OS Xinstalling from third-party packages Third-party Packages A further option for installing Nmap is to use one of the systems @@ -1028,6 +1023,7 @@ install nmap. Nmap will be installed as +Mac OS Xrunning Nmap on Executing Nmap on Mac OS X The terminal emulator in Mac OS X is called @@ -1035,10 +1031,10 @@ install nmap. Nmap will be installed as /Applications/Utilities. Open it and you will see a terminal window. This is where you will type your commands. -sudo + By default the root user is disabled on Mac OS X. To run a scan with -root privileges prefix the command name with sudo, -sudo +root privileges prefix the command name with +sudo,sudo as in sudo nmap -sS target. You will be asked for a password, which is just your normal login @@ -1049,14 +1045,15 @@ be installed. If it was not installed by default it may be available as an optional install on the Mac OS X installation discs. When Zenmap is started, a dialog is displayed requesting that you -type your password. Users with administrator privileges -privileged users +type your password. Users with +administrator privilegesprivileged users may enter their password to allow Zenmap to run as the root user and run more advanced scans. To run Zenmap in unprivileged mode, just select the Cancel button on this dialog. + FreeBSD / OpenBSD / NetBSD @@ -1073,6 +1070,7 @@ popular applications. Instructions for installing Nmap on the most popular *BSD variants follow. OpenBSD Binary Packages and Source Ports Instructions +OpenBSD, installing on According to the OpenBSD FAQ, users @@ -1098,7 +1096,7 @@ Or obtain it from the OpenBSD distribution CD-ROM. FreeBSD Binary Package and Source Ports Instructions -FreeBSD +FreeBSD, installing on The FreeBSD project has a whole chapter @@ -1132,23 +1130,23 @@ chapter referenced above. NetBSD Binary Package Instructions -NetBSD +NetBSD, installing on NetBSD has packaged Nmap for an enormous number of platforms, from the normal i386 to Playstation 2, PowerPC, VAX, SPARC, MIPS, Amiga, ARM, and several platforms that I have never even heard of! Unfortunately they are not very up-to-date. A list of NetBSD Nmap packages is available from and a description of using their package system to install applications is available at . Amiga, HP-UX, IRIX, and Other Platforms -AmigaOS -HP-UX -IRIX +AmigaOS, installing on +HP-UX, installing on +IRIX, installing on One of the wonders of Open Source development is that resources are often biased towards what people find exciting rather than having an exclusive focus on profits as most corporations do. It is along -those lines that the Amiga port came about. Diego Casorran -Casorran, Diegoperformed +those lines that the Amiga port came about. +Diego CasorranCasorran, Diegoperformed most of the work and sent in a clean patch which was integrated into the main Nmap distribution. In general, AmigaOS users should be able to simply follow the source compilation instructions in SGI IRIX. The Nmap project mostly depends on the user community to maintain adequate support for these systems. If you have trouble, try sending a report with full details to the nmap-dev mailing list -(nmap-dev@insecure.org). -nmap-dev mailing list +(nmap-dev@insecure.org).nmap-dev mailing list If you develop a patch which improves support on your platform, please email it to nmap-dev or to me at fyodor@insecure.org. @@ -1182,8 +1179,7 @@ megabytes of disk space it consumes. How to remove Nmap depends on how you installed it initially (see previous sections). Ease of removal (and other maintenance) is a major advantage of most binary packages. For example, when Nmap is installed using -the RPM -RPM +the RPMRPM system common on Linux distributions, it can be removed by running the command rpm -e nmap zenmap as root. Analogous options are offered by diff --git a/docs/refguide.xml b/docs/refguide.xml index 088929df7..771500d21 100644 --- a/docs/refguide.xml +++ b/docs/refguide.xml @@ -51,30 +51,30 @@ The output from Nmap is a list of scanned targets, with supplemental information on each depending on the options used. Key among that information is the interesting ports - table. - portsinteresting + table.portsinteresting That table lists the port number and protocol, service name, and state. The state is either open, filtered, closed, or unfiltered. - open port state - Open means that an application on the target machine is listening for + Openopen port state + means that an application on the target machine is listening for connections/packets on that port. - filtered port state - Filtered means that a firewall, filter, or other network + Filteredfiltered port state + means that a firewall, filter, or other network obstacle is blocking the port so that Nmap cannot tell whether it is open or closed. - closed port state - Closed ports have no application listening on them, + Closedclosed port state + ports have no application listening on them, though they could open up at any time. - unfiltered port state - Ports are classified as unfiltered when they are + Ports are classified as + unfilteredunfiltered port state + when they are responsive to Nmap's probes, but Nmap cannot determine whether they are open or closed. - open|filtered port state - closed|filtered port state - Nmap reports the state combinations open|filtered and - closed|filtered when it cannot determine which + Nmap reports the state combinations + open|filteredopen|filtered port state + and closed|filteredclosed|filtered port state + when it cannot determine which of the two states describe a port. The port table may also include software version details when version detection has been requested. When an IP protocol scan is requested @@ -170,8 +170,8 @@ option argument) is treated as a target host specification. The simplest case is to specify a target IP address or hostname for scanning. Sometimes you wish to scan a whole network of adjacent hosts. -For this, Nmap supports CIDR-style addressing. -CIDR (Classless Inter-Domain Routing) +For this, Nmap supports +CIDR-style addressing.CIDR (Classless Inter-Domain Routing) You can append /numbits to an IP address or hostname and Nmap will scan every IP address for which the first @@ -342,8 +342,7 @@ you would expect. used for any targets which are on a local ethernet network. For unprivileged Unix shell users, a SYN packet is sent instead of the ACK using the connect() - system call. - unprivileged userslimitations of + system call.unprivileged userslimitations of These defaults are equivalent to the options. This host discovery is often sufficient when scanning local networks, but a more @@ -354,8 +353,8 @@ you would expect. ping types) can be combined. You can increase your odds of penetrating strict firewalls by sending many probe types using different TCP ports/flags and ICMP codes. Also note that ARP - discovery () - + discovery + () is done by default against targets on a local ethernet network even if you specify other options, because it is almost always faster @@ -435,8 +434,7 @@ you would expect. (using a connect() call) to port 80 on the target. When a privileged user tries to scan targets on a local ethernet network, ARP requests - () - + () are used unless was specified. The option can be combined with any of the @@ -509,8 +507,8 @@ you would expect. are attempting to establish a connection. Normally the destination port will be closed, and a RST (reset) packet sent back. If the port happens to be open, the target will - take the second step of a TCP 3-way-handshake - three-way handshake + take the second step of a TCP + 3-way-handshakethree-way handshake by responding with a SYN/ACK TCP packet. The machine running Nmap then tears down the nascent connection by responding with a RST @@ -525,16 +523,13 @@ you would expect. Nmap that the host is available and responsive. On Unix boxes, only the privileged user - root - privileged users - is generally able to send and - receive raw TCP packets. - raw packets + rootprivileged users + is generally able to send and receive + raw TCP packets.raw packets For unprivileged users, a - workaround is automatically employed whereby the connect() - system call is initiated against each target port. - unprivileged userslimitations of - This has + workaround is automatically employedunprivileged userslimitations of + whereby the connect() system call is initiated against each + target port. This has the effect of sending a SYN packet to the target host, in an attempt to establish a connection. If connect() returns with a quick success or an ECONNREFUSED failure, the @@ -543,8 +538,7 @@ you would expect. is left hanging until a timeout is reached, the host is marked as down. This workaround is also used for IPv6 connections, as raw IPv6 packet building support is not yet - available in Nmap. - IPv6limitations of + available in Nmap.IPv6limitations of @@ -584,8 +578,7 @@ you would expect. outgoing connections to the Internet. This non-stateful approach takes up few resources on the firewall/router and is widely supported by hardware and software filters. The - Linux Netfilter/iptables - iptables + Linux Netfilter/iptablesiptables firewall software offers the convenience option to implement this stateless approach. When stateless firewall rules such as @@ -623,10 +616,8 @@ you would expect. and options. If no ports are specified, the default is 31338. This default can be configured at compile-time by changing - DEFAULT_UDP_PROBE_PORT_SPEC - DEFAULT_UDP_PROBE_PORT_SPEC - in nmap.h. - nmap.h + DEFAULT_UDP_PROBE_PORT_SPECDEFAULT_UDP_PROBE_PORT_SPEC + in nmap.h.nmap.h A highly uncommon port is used by default because sending to open ports is often undesirable for this particular scan type. @@ -672,8 +663,7 @@ you would expect. ping program. Nmap sends an ICMP type 8 (echo request) packet to the target IP addresses, expecting a type 0 (echo reply) in return from available - hosts. - ICMP echo + hosts.ICMP echo Unfortunately for network explorers, many hosts and firewalls now block these packets, rather than responding as required by IP packets for ICMP (protocol 1), IGMP (protocol 2), and IP-in-IP (protocol 4). The default protocols can be configured at compile-time by changing - DEFAULT_PROTO_PROBE_PORT_SPEC - DEFAULT_PROTO_PROBE_PORT_SPEC - in nmap.h. - nmap.h + DEFAULT_PROTO_PROBE_PORT_SPECDEFAULT_PROTO_PROBE_PORT_SPEC + in nmap.h.nmap.h Note that for the ICMP, IGMP, TCP (protocol 6), and UDP (protocol 17), the packets are sent with the proper protocol headers while other protocols are sent with no additional data @@ -814,8 +802,8 @@ Nmap can provide is determined by the type of scan or ping. The SYN scan and SYN ping ( and ) are very detailed, but the TCP connect scan () is limited by the implementation of the connect system call. This feature is automatically enabled by -the debug option () -implied by +the debug option +()implied by and the results are stored in XML log files even if this option is not specified. @@ -1018,8 +1006,8 @@ jalopy to a real mechanic, he invariably fishes around in a huge tool chest unti pulling out the perfect gizmo which makes the job seem effortless. The art of port scanning is similar. Experts understand the dozens of scan techniques and choose the appropriate one (or combination) for a -given task. Inexperienced users and script kiddies, -script kiddies +given task. Inexperienced users and +script kiddies,script kiddies on the other hand, try to solve every problem with the default SYN scan. Since Nmap is free, the only barrier to port scanning mastery is knowledge. That @@ -1027,10 +1015,10 @@ certainly beats the automotive world, where it may take great skill to determine that you need a strut spring compressor, then you still have to pay thousands of dollars for it. -Most of the scan types are only available to privileged users. -privileged users -This is because they send and receive raw packets, -raw packets +Most of the scan types are only available to +privileged users.privileged users +This is because they send and receive +raw packets,raw packets which requires root access on Unix systems. Using an administrator account on Windows is recommended, though Nmap sometimes works for unprivileged users on that @@ -1180,8 +1168,8 @@ out and then conduct retransmissions just in case the probe or response were lost. Closed ports are often an even bigger problem. They usually send back an ICMP port unreachable error. But unlike the RST packets sent by closed TCP ports in response to a SYN or connect -scan, many hosts rate limit ICMP port unreachable messages by default. -rate limiting +scan, many hosts rate limitrate limiting +ICMP port unreachable messages by default. Linux and Solaris are particularly strict about this. For example, the Linux 2.4.20 kernel limits destination unreachable messages to one per second (in net/ipv4/icmp.c). @@ -1335,10 +1323,10 @@ ports, then those three may very well be the truly open ones. -The Maimon scan is named after its discoverer, Uriel Maimon. -Maimon, Uriel -He described the technique in Phrack Magazine issue #49 (November 1996). -Phrack +The Maimon scan is named after its discoverer, +Uriel Maimon.Maimon, Uriel +He described the technique in +Phrack Magazine issue #49 (November 1996).Phrack Nmap, which included this technique, was released two issues later. This technique is exactly the same as NULL, FIN, and Xmas scans, except that the probe is FIN/ACK. According to RFC 793 (TCP), a RST packet @@ -1358,10 +1346,10 @@ simply drop the packet if the port is open. Truly advanced Nmap users need not limit themselves to the canned scan types offered. The option allows -you to design your own scan by specifying arbitrary TCP flags. -TCP flags -Let your creative juices flow, while evading intrusion detection systems -intrusion detection systemsevading +you to design your own scan by specifying arbitrary +TCP flags.TCP flags +Let your creative juices flow, while evading +intrusion detection systemsintrusion detection systemsevading whose vendors simply paged through the Nmap man page adding specific rules! The argument can be a numerical @@ -1422,9 +1410,9 @@ used. listing shows open ports from the perspective of the zombie host. So you can try scanning a target using - various zombies that you think might be trusted (via - router/packet filter rules). - trust relationships + various zombies that you think might be + trustedtrust relationships + (via router/packet filter rules). You can add a colon followed by a port number to the @@ -1455,12 +1443,11 @@ close enough to a port scan that it belongs here. Besides being useful in its own right, protocol scan demonstrates the power of open-source software. While the fundamental idea is pretty simple, I had not thought to add it nor received any -requests for such functionality. Then in the summer of 2000, Gerhard -Rieger -Rieger, Gerhard +requests for such functionality. Then in the summer of 2000, +Gerhard RiegerRieger, Gerhard conceived the idea, wrote an excellent patch implementing it, -and sent it to the nmap-hackers mailing list. -nmap-hackers mailing list +and sent it to the +nmap-hackers mailing list.nmap-hackers mailing list I incorporated that patch into the Nmap tree and released a new version the next day. Few pieces of commercial software have users enthusiastic enough to design and contribute their own @@ -1566,8 +1553,8 @@ way. beginning and/or end values of a range may be omitted, causing Nmap to use 1 and 65535, respectively. So you can specify to scan ports from 1 through - 65535. Scanning port zero - port zero + 65535. Scanning + port zeroport zero is allowed if you specify it explicitly. For IP protocol scanning (), this option specifies the protocol numbers you wish to scan for @@ -1616,9 +1603,9 @@ way. (about 1650 ports) isn't dramatic. The difference can be enormous if you specify your own tiny nmap-services file using the - or options. - - + + or + options. @@ -1650,17 +1637,16 @@ way. Point Nmap at a remote machine and it might tell you that ports 25/tcp, 80/tcp, and 53/udp are open. Using its - nmap-services - nmap-services - database of about 2,200 well-known services, - well-known ports + nmap-servicesnmap-services + database of about 2,200 + well-known services,well-known ports Nmap would report that those ports probably correspond to a mail server (SMTP), web server (HTTP), and name server (DNS) respectively. This lookup is usually accurate—the vast majority of daemons listening on TCP port 25 are, in fact, mail servers. However, you should not bet your security on this! - People can and do run services on strange ports. - non-standard ports + People can and do run services on + strange ports.non-standard ports Even if Nmap is right, and the hypothetical server above is @@ -1676,8 +1662,7 @@ way. After TCP and/or UDP ports are discovered using one of the other scan methods, version detection interrogates those ports to determine more about what is actually running. The - nmap-service-probes - nmap-service-probes + nmap-service-probesnmap-service-probes database contains probes for querying various services and match expressions to recognize and parse responses. Nmap tries to determine the service protocol @@ -1689,12 +1674,10 @@ way. version, or the KaZaA user name). Of course, most services don't provide all of this information. If Nmap was compiled with OpenSSL support, it will connect to SSL servers to deduce the - service listening behind that encryption layer. - SSLin version detection + service listening behind that encryption layer.SSLin version detection When RPC services are - discovered, the Nmap RPC grinder () - RPC grinder - + discovered, the Nmap RPC grinderRPC grinder + () is automatically used to determine the RPC program and version numbers. Some UDP ports are left in the open|filtered state after a UDP port scan is @@ -1720,8 +1703,7 @@ way. on the port. Please take a couple minutes to make the submission so that your find can benefit everyone. Thanks to these submissions, Nmap has about 3,000 pattern matches for more than - 350 protocols such as SMTP, FTP, HTTP, etc. - submission of service fingerprints + 350 protocols such as SMTP, FTP, HTTP, etc.submission of service fingerprints Version detection is enabled and controlled with the @@ -1851,8 +1833,8 @@ way. what program and version number they serve up. Thus you can effectively obtain the same info as rpcinfo -p even if the target's portmapper is behind a firewall (or protected by - TCP wrappers). Decoys do not currently work with RPC scan. - decoyswhich scans use + TCP wrappers). Decoys do not currently work with + RPC scan.decoyswhich scans use This is automatically enabled as part of version scan () if you request that. As version detection includes this and is much more comprehensive, @@ -1875,8 +1857,7 @@ way. in the responses. After performing dozens of tests such as TCP ISN sampling, TCP options support and ordering, IP ID sampling, and the initial window size check, Nmap compares the results to its - nmap-os-db - nmap-os-db + nmap-os-dbnmap-os-db database of more than a thousand known OS fingerprints and prints out the OS details if there is a match. Each fingerprint includes a freeform textual description of the @@ -2083,8 +2064,8 @@ way. To reflect those different uses and to simplify the choice of which scripts to run, each script contains a field associating it with one or more of the above mentioned categories. To maintain the matching from scripts to - categories a file called script.db - script.db + categories a file called + script.dbscript.db is installed along with the distributed scripts. Therefore, if you, for example, want to see if a machine is infected by any worm Nmap provides a script for you can simply @@ -2099,12 +2080,11 @@ way. An NSE script basically is a chunk of Lua-code which has (among some informational fields, like name, id and categories) 2 functions: a test whether the particular script should be run against a certain host or port - (called a hostrule - hostrule script variable - or portrule - portrule script variable - respectively) and an action - action script variable + (called a + hostrulehostrule script variable + or portruleportrule script variable + respectively) and an + actionaction script variable to be carried out if the test returns true. Scripts have access to most information gathered by Nmap during earlier stages. For each host this includes the IP address, hostname and (if @@ -2142,14 +2122,10 @@ way. Runs a script scan (like ) with the scripts you have chosen rather than the defaults. Arguments can be script categories, single scripts or directories with scripts which are to be run against the target hosts instead of the default set. Nmap will try to interpret the arguments at first as categories and afterwards as files or directories. Absolute paths are used as is, relative paths are searched in the following places until found: - ---datadir/; -NMAPDIR environment variable -$NMAPDIR/; -~/.nmap/ (not searched on Windows); -.nmap directory -NMAPDATADIR -NMAPDATADIR/ or +--datadir/; +$NMAPDIR/;NMAPDIR environment variable +~/.nmap/ (not searched on Windows);.nmap directory +NMAPDATADIR/ orNMAPDATADIR ./. A scripts/ subdirectory is also tried in each of these. Give the argument all to execute all scripts in the Nmap script database. @@ -2174,7 +2150,6 @@ categories. - script arguments script arguments @@ -2387,8 +2362,8 @@ timing out and retransmitting while the response is in transit. If all the hosts are on a local network, 100 milliseconds is a reasonable aggressive value. If routing is involved, ping a host on the network first with the ICMP -ping utility, or with a custom packet crafter such as hping2 -hping2 +ping utility, or with a custom packet crafter such as +hping2hping2 that is more likely to get through a firewall. Look at the maximum round trip time out of ten packets or so. You might want to double that for the @@ -2401,9 +2376,8 @@ exceed 1000 ms. could be useful when a network is so unreliable that even Nmap's default is too aggressive. Since Nmap only reduces the timeout down to the minimum when the network seems to be reliable, this need is -unusual and should be reported as a bug to the nmap-dev mailing -list. -nmap-dev mailing list +unusual and should be reported as a bug to the +nmap-dev mailing list.nmap-dev mailing list @@ -2502,8 +2476,8 @@ packet retransmissions and possible missed ports when the target implements strict rate limiting. Another use of is to evade -threshold based intrusion detection and prevention systems (IDS/IPS). -intrusion detection systemsevading +threshold based intrusion detection and prevention systems +(IDS/IPS).intrusion detection systemsevading @@ -2544,9 +2518,7 @@ faster than a network can support may lead to a loss of accuracy. In some cases, using a faster rate can make a scan take longer than it would with a slower rate. This is because Nmap's adaptive -retransmission -adaptive retransmissionretransmission -retransmission +retransmissionadaptive retransmissionretransmissionretransmission will detect the network congestion caused by an excessive scanning rate and increase the number of retransmissions in order to improve accuracy. So even though packets are sent at a higher rate, more packets are sent @@ -2568,9 +2540,10 @@ timing. -Many hosts have long used rate limiting to reduce the number +Many hosts have long used +rate limitingrate limiting +to reduce the number of ICMP error messages (such as port-unreachable errors) they send. -rate limiting Some systems now apply similar rate limits to the RST (reset) packets they generate. This can slow Nmap down dramatically as it adjusts its timing to reflect those rate limits. You can tell Nmap to @@ -2597,7 +2570,6 @@ worth the extra time. <paranoid|sneaky|polite|normal|aggressive|insane> (Set a timing template) - timing templates timing templatesparanoid, sneaky, polite, normal, aggressive, and insane @@ -2615,20 +2587,14 @@ Moreover, choosing the appropriate values can sometimes take more time than the scan you are trying to optimize. So Nmap offers a simpler approach, with six timing templates. You can specify them with the option and their number (0–5) or their name. -The template names are  (), -paranoid () timing template - (), -sneaky () timing template - (), -polite () timing template - (), -normal () timing template - (), and -aggressive () timing template - (). -insane () timing template +The template names are + (),paranoid () timing template + (),sneaky () timing template + (),polite () timing template + (),normal () timing template + (),aggressive () timing template +and  ().insane () timing template The first two are for IDS evasion. -intrusion detection systemsevading Polite mode slows down the scan to use less bandwidth and target machine resources. Normal mode is the default and so does nothing. Aggressive mode speeds scans up by @@ -2641,11 +2607,9 @@ for speed. wish to be, while leaving Nmap to pick the exact timing values. The templates also make some minor speed adjustments for which fine-grained control options do not currently exist. For example, - -aggressive () timing template +aggressive () timing template prohibits the dynamic scan delay from exceeding 10 ms for TCP ports and caps that value at 5 ms. -insane () timing template Templates can be used in combination with fine-grained controls, and the fine-grained controls will you specify will take precedence over the timing template default for that parameter. I @@ -2660,8 +2624,7 @@ recommend always using . Some people love sometimes specify because they think it is less likely to crash hosts or because they consider themselves to be polite in general. They often don't realize just how slow -polite () timing template +politepolite () timing template really is. Their scan may take ten times longer than a default scan. Machine crashes and bandwidth problems are rare with the @@ -2670,10 +2633,9 @@ recommend that for cautious scanners. Omitting version detection is far more effective than playing with timing values at reducing these problems. -While -paranoid () timing template -and -sneaky () timing template +While +paranoid () timing template +and sneaky () timing template may be useful for avoiding IDS alerts, they will take an extraordinarily long time to scan thousands of machines or ports. For such a long scan, @@ -2686,14 +2648,12 @@ so only one port is scanned at a time, and waiting five minutes between sending each probe. and are similar but they only wait 15 seconds and 0.4 seconds, respectively, between probes. is Nmap's -default behavior, which includes parallelization. -normal () timing template +default behavior, which includes +parallelization.normal () timing template -aggressive () timing template does the equivalent of and sets the maximum TCP scan delay to 10 milliseconds. -insane () timing template does the equivalent of as well as @@ -2744,8 +2704,8 @@ increasingly monitoring traffic with intrusion detection systems (IDS). All of the major IDSs ship with rules designed to detect Nmap scans because scans are sometimes a precursor to attacks. Many of these products have recently morphed into intrusion -prevention systems (IPS) -intrusion prevention systemsintrusion detection systems +prevention systems +(IPS)intrusion prevention systemsintrusion detection systems that actively block traffic deemed malicious. Unfortunately for network administrators and IDS vendors, reliably detecting bad intentions by analyzing packet @@ -2796,8 +2756,7 @@ lists the relevant options and describes what they do. packets. Two with eight bytes of the TCP header, and one with the final four. Of course each fragment also has an IP header. Specify again to use 16 bytes per fragment - (reducing the number of fragments). - giving twice for small fragments + (reducing the number of fragments).giving twice Or you can specify your own offset size with the option. Don't also specify if you use . The offset must be a @@ -2809,14 +2768,14 @@ lists the relevant options and describes what they do. this because fragments may take different routes into their networks. Some source systems defragment outgoing packets in the kernel. Linux - with the iptables - iptables + with the + iptablesiptables connection tracking module is one such - example. Do a scan while a sniffer such as Wireshark - Wireshark + example. Do a scan while a sniffer such as + WiresharkWireshark is running to ensure that sent packets are fragmented. If your host - OS is causing problems, try the - + OS is causing problems, try the + option to bypass the IP layer and send raw ethernet frames. @@ -2840,19 +2799,18 @@ lists the relevant options and describes what they do. hiding your IP address. Separate each decoy host with commas, and you can - optionally use ME - ME (decoy address) + optionally use + MEME (decoy address) as one of the decoys to represent the position for your real IP address. If you put ME in the 6th position or later, some - common port scan detectors (such as Solar Designer's - Solar Designer - excellent Scanlogd) - Scanlogd + common port scan detectors (such as + Solar Designer'sSolar Designer + excellent Scanlogd)Scanlogd are unlikely to show your IP address at all. If you don't use ME, Nmap will put - you in a random position. You can also use RND - RND (decoy address) + you in a random position. You can also use + RNDRND (decoy address) to generate a random, non-reserved IP address, or RND:number to generate number addresses. Note that the hosts @@ -2912,7 +2870,7 @@ lists the relevant options and describes what they do. (Use specified interface) - interface + interface @@ -2987,8 +2945,7 @@ support the option completely, as does UDP scan. bytes and ICMP echo requests are just 28. This option tells Nmap to append the given number of random bytes to most of the packets it sends. OS detection () packets - are not affected - no effect in OS detection + are not affectedno effect in OS detection because accuracy there requires probe consistency, but most pinging and portscan packets support this. It slows things down a little, but can make a scan slightly less conspicuous. @@ -3029,13 +2986,11 @@ support the option completely, as does UDP scan. Nmap also offers a shortcut mechanism for specifying options. Simply pass the letter R, T, or U to request - record-route, - record route IP option - record-timestamp, - record timestamp IP option + record-route,record route IP option + record-timestamp,record timestamp IP option or both options together, - respectively. Loose or strict source routing - source routing + respectively. + Loose or strict source routingsource routing may be specified with an L or S followed by a space and then a space-separated list of IP addresses. @@ -3075,17 +3030,14 @@ support the option completely, as does UDP scan. to various network monitoring systems, especially when you combine it with slow timing options. If you want to randomize over larger group sizes, increase - PING_GROUP_SZ - PING_GROUP_SZ - in nmap.h - nmap.h + PING_GROUP_SZPING_GROUP_SZ + in nmap.hnmap.h and recompile. An alternative solution is to generate the target IP list with a list scan (), randomize it with a Perl script, then provide the whole list to Nmap with - . - randomizing hosts with + .randomizing hosts with @@ -3102,8 +3054,7 @@ support the option completely, as does UDP scan. Asks Nmap to use the given MAC address MAC address for all of the raw ethernet frames it sends. This option implies - - implied by + implied by to ensure that Nmap actually sends ethernet-level packets. The MAC given can take several formats. If it is simply the number 0, Nmap chooses a completely random MAC address @@ -3114,9 +3065,7 @@ support the option completely, as does UDP scan. argument isn't a 0 or hex string, Nmap looks through nmap-mac-prefixes to find a vendor name containing the given string (it is case insensitive). If a match is found, Nmap uses the - vendor's OUI (3-byte prefix) - organizationally unique identifier (OUI) - organizationally unique identifier (OUI)nmap-mac-prefixes + vendor's OUI (3-byte prefix)organizationally unique identifier (OUI)organizationally unique identifier (OUI)nmap-mac-prefixes and fills out the remaining 3 bytes randomly. Valid argument examples are Apple, 0, 01:02:03:04:05:06, deadbeefcafe, 0020F2, and Cisco. This option only affects raw packet scans such as SYN scan or OS detection, not connection-oriented features such as version detection or the Nmap Scripting Engine. @@ -3168,29 +3117,26 @@ files, which Nmap can append to or clobber. Output files may also be used to resume aborted scans. Nmap makes output available in five different formats. -The default is called interactive output, -interactive output -and it is sent to standard output (stdout). -stdout -standard output -There is also normal output, -normal output +The default is called +interactive output,interactive output +and it is sent to +standard output (stdout).stdoutstandard output +There is also +normal output,normal output which is similar to interactive except that it displays less runtime information and warnings since it is expected to be analyzed after the scan completes rather than interactively. -XML output -XML output +XML outputXML output is one of the most important output types, as it can be converted to HTML, easily parsed by programs such as Nmap graphical user interfaces, or imported into databases. -The two remaining output types are the simple grepable -output -grepable output +The two remaining output types are the simple +grepable outputgrepable output which includes most information for a target host on -a single line, and sCRiPt KiDDi3 0utPUt -scR1pT kIddI3 output +a single line, and +sCRiPt KiDDi3 0utPUtscR1pT kIddI3 output for users who consider themselves |<-r4d. @@ -3217,14 +3163,9 @@ character as the argument to one of the format types. This causes Nmap to deactivate interactive output, and instead print results in the format you specified to the standard output stream. So the command nmap -oX - target will send only XML output to -stdout. -stdout -standard output -outputto stdout with - +stdout.outputto stdout with - Serious errors may still be printed to the normal error -stream, stderr. -standard error -stderr +stream, stderr.standard errorstderr Unlike some Nmap arguments, the space between the logfile option @@ -3236,8 +3177,8 @@ compatibility feature of Nmap will cause the creation of G- and Xscan.xml respectively. -All of these arguments support strftime()-like -strftime conversions in filenames +All of these arguments support +strftime()-likestrftime conversions in filenames conversions in the filename. %H, %M, %S, %m, %d, %y, and %Y are all exactly the same @@ -3355,8 +3296,7 @@ are running Solaris takes only a simple grep to identify the hosts, piped to an awk or cut command to print the desired fields. Grepable output consists of comments (lines starting with a -pound (#)) -grepable outputcomments in +pound (#))grepable outputcomments in and target lines. A target line includes a combination of 6 labeled fields, separated by tabs and followed with a colon. The fields are Host, Ports, @@ -3448,8 +3388,8 @@ format is available debugging is available to flood you with much more! As with the verbosity option (), debugging is enabled with a command-line flag () and the debug level can be -increased by specifying it multiple times. -giving more than once +increased by specifying it +multiple times.giving more than once Alternatively, you can set a debug level by giving an argument to . For example, sets level nine. That is the highest @@ -3463,8 +3403,8 @@ self-explanatory. You may get something like: Timeout vals: srtt: -1 rttvar: -1 to: 1000000 delta 14987 ==> srtt: 14987 rttvar: 14987 to: 100000. If you don't understand a line, your only recourses are to ignore it, look it up in the source code, or request help from -the development list (nmap-dev). -nmap-dev mailing list +the development list +(nmap-dev).nmap-dev mailing list Some lines are self explanatory, but the messages become more obscure as the debug level is increased. @@ -3713,9 +3653,8 @@ overwhelming requests. Specify to only see configured for IPv6. If your ISP (like most of them) does not allocate IPv6 addresses to you, free tunnel brokers are widely available and work fine with Nmap. I use the free - IPv6 tunnel broker service at - . - IPv6 tunnel broker + IPv6 tunnel brokerIPv6 tunnel broker + service at . Other tunnel brokers are listed at Wikipedia. 6to4 tunnels are another popular, @@ -3766,15 +3705,13 @@ overwhelming requests. Specify to only see nmap-os-db. If the location of any of these files has been specified (using the or options), - - that location is used for that file. After that, Nmap searches these files in the directory specified with the option (if any). Any files not found there, are searched for in the directory specified by the NMAPDIR environmental variableNMAPDIR environment variable. - Next comes ~/.nmap - .nmap directory + Next comes + ~/.nmap.nmap directory for real and effective UIDs (POSIX systems only) or location of the Nmap executable (Win32 only), and then a compiled-in location such as /usr/local/share/nmap or /usr/share/nmap @@ -3824,8 +3761,8 @@ overwhelming requests. Specify to only see Asks Nmap to send packets at the raw ethernet (data link) layer rather than the higher IP (network) layer. By default, Nmap chooses the one which is generally best for - the platform it is running on. Raw sockets (IP layer) - raw sockets + the platform it is running on. + Raw sockets (IP layer)raw sockets are generally most efficient for Unix machines, while ethernet frames are required for Windows operation since Microsoft @@ -3859,9 +3796,8 @@ overwhelming requests. Specify to only see Tells Nmap to simply assume that it is privileged enough to perform raw socket sends, packet sniffing, and - similar operations that usually require root privileges - privileged users - authorized usersprivileged users + similar operations that usually require + root privilegesprivileged usersauthorized usersprivileged users on Unix systems. By default Nmap quits if such operations are requested but geteuid() is not zero. is useful with Linux @@ -3869,8 +3805,9 @@ overwhelming requests. Specify to only see configured to allow unprivileged users to perform raw-packet scans. Be sure to provide this option flag before any flags for options that require privileges (SYN scan, OS detection, - etc.). The NMAP_PRIVILEGED environmental variable - NMAP_PRIVILEGED environment variable + etc.). The + NMAP_PRIVILEGEDNMAP_PRIVILEGED environment variable + environmental variable may be set as an equivalent alternative to . @@ -3888,11 +3825,11 @@ overwhelming requests. Specify to only see This option is the opposite of . It tells Nmap to treat the user as lacking network raw socket and sniffing privileges. - unprivileged users This is useful for testing, debugging, or when the raw network functionality of your operating system is somehow - broken. The NMAP_UNPRIVILEGED environmental variable - NMAP_UNPRIVILEGED environment variable + broken. The + NMAP_UNPRIVILEGEDNMAP_UNPRIVILEGED environment variable + environmental variable may be set as an equivalent alternative to . @@ -3935,8 +3872,8 @@ overwhelming requests. Specify to only see help. This option is rarely used because proper shells are usually more familiar and feature-complete. This option includes a bang (!) operator for executing shell commands, - which is one of many reasons not to install Nmap setuid root. - setuid, why Nmap shouldn't be + which is one of many reasons not to install Nmap + setuid root.setuid, why Nmap shouldn't be @@ -4098,7 +4035,6 @@ overwhelming requests. Specify to only see probing one port on each target host anyway. - example of example of example of nmap -PN -p80 -oX logs/pb-port80scan.xml -oG @@ -4121,8 +4057,7 @@ overwhelming requests. Specify to only see do some research to determine whether it has already been discovered and addressed. Try Googling the error message or browsing the nmap-dev archives at . - nmap-dev mailing list + url="http://seclists.org/" />.nmap-dev mailing list Read this full manual page as well. If nothing comes of this, mail a bug report to nmap-dev@insecure.org. Please include everything @@ -4148,8 +4083,7 @@ overwhelming requests. Specify to only see Hundreds of people have made valuable contributions to Nmap over the years. These are detailed in the - CHANGELOG - changelog + CHANGELOGchangelog file which is distributed with Nmap and also available from . @@ -4160,4 +4094,4 @@ overwhelming requests. Specify to only see &legal-notices; -reference guide (man page) + diff --git a/docs/scripting.xml b/docs/scripting.xml index ed5c60d9c..a30e3264e 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -13,11 +13,11 @@ growing and diverse set of scripts distributed with Nmap, or write their own to meet custom needs. - The Nmap project would like to thank Diman Todorov - Todorov, Diman + The Nmap project would like to thank + Diman TodorovTodorov, Diman for his excellent work building the initial NSE implementation and - writing much of this documentation. Stoiko Ivanov - Ivanov, Stoiko + writing much of this documentation. + Stoiko IvanovIvanov, Stoiko also contributed greatly. The tasks we had in mind when creating the system are: @@ -73,8 +73,8 @@ backdoors to enable later reentry. Some of these can be detected by Nmap's regular expression based version detection. For example, within hours of the MyDoom worm hitting the - Internet, Jay Moran - Moran, Jay + Internet, + Jay MoranMoran, Jay posted an Nmap version detection probe and signature so that others could quickly scan their networks. For more complex worms and backdoors, NSE is needed @@ -89,12 +89,11 @@ As a general scripting language, NSE could even be used to exploit vulnerabilities rather than just find them. The capability to add custom exploit scripts may be valuable - for some people (particularly penetration testers), - penetration testing + for some people (particularly + penetration testers),penetration testing though we aren't planning to turn Nmap into an exploitation framework like - Metasploit. - Metasploit + Metasploit.Metasploit @@ -108,9 +107,8 @@ Scripts are written in the - embedded Lua programming language. - Lua programming language - Lua programming languageNmap Scripting Engine + embedded + Lua programming language.Lua programming languageNmap Scripting Engine The language itself is well documented in the books Programming @@ -133,15 +131,14 @@ The reference manual is also - NSE is activated with the - - option (or - + NSE is activated with the + + option (or + if you wish to specify a custom set of - scripts) and results are integrated into Nmap normal - normal output - and XML output. - XML output + scripts) and results are integrated into Nmap + normalnormal output + and XML output.XML output Two types of scripts are supported: service and host scripts. Service scripts relate to a certain open port (service) on the target host, and any results they produce are included @@ -157,8 +154,8 @@ The reference manual is also username it is running under, and HTML Title, which simply grabs the title of the root path of any web servers found. A sample host script is RIPE Query, - which looks up and reports target IP ownership information. - script names, examples of + which looks up and reports target IP ownership + information.script names, examples of @@ -190,21 +187,18 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds Usage and Examples While NSE has a complex implementation for efficiency, it is - strikingly easy to use. Simply specify - + strikingly easy to use. Simply specify + to enable the most common scripts. Or specify the - - + option to choose your own scripts to execute by providing categories, script file names, or the name of directories full of scripts you wish to execute. You can customize some scripts by providing arguments to them via the - - - option. The two remaining options, - - and , - + + option. The two remaining options, + + and , are generally only used for script debugging and development. @@ -408,16 +402,12 @@ with scripts which are to be run against the target hosts instead of the default set. Nmap will try to interpret the arguments at first as categories and afterwards as files or directories. Absolute paths are used as is, relative paths are -searched in the following places until found: -data filesdirectory search order -scripts, location of +searched in the following places until +found:data filesdirectory search orderscripts, location of --datadir/; -NMAPDIR environment variable -$NMAPDIR/; -.nmap directory -~/.nmap/ (not searched on Windows); -NMAPDATADIR -NMAPDATADIR/ or +$NMAPDIR/;NMAPDIR environment variable +~/.nmap/ (not searched on Windows);.nmap directory +NMAPDATADIR/ orNMAPDATADIR ./. A scripts/ subdirectory is also tried in each of these. Give the argument all to execute all scripts in the Nmap script database. @@ -433,8 +423,7 @@ extension does not have to be nse. Nmap scripts are stored in a scripts subdirectory of the Nmap data directory (see ) by default. Scripts are indexed in a database stored in -scripts/script.db. -script.db +scripts/script.db.script.db The database lists all of the scripts in each category. A single script may be in several categories. @@ -489,7 +478,6 @@ categories. specified with the option. For efficiency reasons, NSE generates a script.db - script.db file which maps categories to the scripts they contain. If you changed tag directives or added/removed scripts, run @@ -501,11 +489,11 @@ categories. Some of the Nmap options have effects on script scans. The most - prominent of these is . - + prominent of these is + . A version scan executes - the scripts in the version category. - version script category + the scripts in the + version category.version script category The scripts in this category are slightly different than other scripts. Their output blends in with the version scan and they do not produce any @@ -513,8 +501,7 @@ categories. Another option which has effect on the scripting engine is - . - features enabled by + .features enabled by The advanced/aggressive mode of Nmap implies the option . @@ -560,8 +547,7 @@ categories. should be kept short to conserve space in Nmap output, while still being meaningful enough for users to recognize. Some good examples are RIPE query, HTML - title, and Kibuv worm. - script names, examples of + title, and Kibuv worm.script names, examples of @@ -647,11 +633,9 @@ that. evaluates to true, the script action is performed. Otherwise the action is skipped. Port rules are only matched against TCP or UDP ports in the - open, open|filtered or - unfiltered - open port state - open|filtered port state - unfiltered port state + open,open port state + open|filtered oropen|filtered port state + unfilteredunfiltered port state states. Host rules are matched exactly once against every scanned host. The action, like the rule, is a Lua function, which takes a host and port table as arguments. If the script is @@ -717,8 +701,7 @@ that. extended with libraries for interfacing with Nmap. The Nmap API is in the Lua namespace nmap. This means that all calls to resources provided by Nmap have an - nmap prefix. - nmap NSE module + nmap prefix.nmap NSE module nmap.new_socket(), for example, returns a new socket wrapper object. The Nmap library layer also takes care of initializing the Lua context, scheduling parallel @@ -774,12 +757,11 @@ that. Bitwise Logical Operations bit NSE module - Lua does not provide bitwise logical operations. - bitwise operations in NSE + Lua does not provide + bitwise logical operations.bitwise operations in NSE Since they - are often useful for low-level network communication, Reuben - Thomas' - Thomas, Reuben + are often useful for low-level network communication, + Reuben Thomas'Thomas, Reuben bitwise operation library for Lua has been integrated into NSE. The arguments to the bitwise operation @@ -897,8 +879,7 @@ that. functionality Lua provides, it's not very convenient. Therefore the BinLib has been added to NSE, based on lpack - by Luiz Henrique de Figueiredo. - Henrique de Figueiredo, Luiz + by Luiz Henrique de Figueiredo.Henrique de Figueiredo, Luiz The BinLib functions take a format string to encode and decode binary data. The operators of the format string are shown in . @@ -989,10 +970,8 @@ that. powerful as standard regular expressions. So we have integrated Perl compatible regular expressions into Lua using PCRE and a modified version of the Lua PCRE library - written by Reuben Thomas - Thomas, Reuben - and Shmuel Zeigerman. - Zeigerman, Shmuel + written by Reuben ThomasThomas, Reuben + and Shmuel Zeigerman.Zeigerman, Shmuel These are the same sort of regular expressions used by Nmap version detection. The main modification to their library is that @@ -1006,7 +985,6 @@ that. 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. @@ -1769,7 +1747,7 @@ if(s) code_to_be_done_on_match end Data File Parsing Functions datafiles NSE module - data files access to from NSE + data filesaccess to from NSE The datafiles module provides functions for reading and parsing Nmap's data files (e.g. nmap-protocol, nmap-rpc, @@ -1937,8 +1915,8 @@ if(s) code_to_be_done_on_match end NSE scripts have access to several Nmap facilities for writing flexible and elegant scripts. The API provides target host details such as port states and version detection results. It - also offers an interface to the Nsocklibrary - Nsock + also offers an interface to the NsockNsock + library for efficient network I/O. @@ -1948,8 +1926,8 @@ if(s) code_to_be_done_on_match end An effective Nmap scripting engine requires more than just a Lua interpreter. Users need easy access to the information Nmap has learned about the target hosts. This data is passed - as arguments to the NSE action method. - action script variable + as arguments to the NSE + action method.action script variable The arguments, host and port, are Lua tables which contain information on the target against which the script is @@ -2034,8 +2012,7 @@ if(s) code_to_be_done_on_match end - MAC address - MAC address + MAC addressMAC address of the destination host (6-byte long binary string) or nil, if the host is not directly connected. @@ -2046,8 +2023,8 @@ if(s) code_to_be_done_on_match end Our own MAC address, which was used to connect to the - host (either our network card's, or (with ) - + host (either our network card's, or (with + ) the spoofed address). @@ -2056,8 +2033,8 @@ if(s) code_to_be_done_on_match end - A string containing the interface name (dnet-style) - libdnet + A string containing the interface name + (dnet-style)libdnet through which packets to the host are sent. @@ -2246,11 +2223,11 @@ if(s) code_to_be_done_on_match end - Returns the debugging level - debuggingin NSE + Returns the + debugging leveldebuggingin NSE as a non-negative integer. The - debugging level can be set with the - + debugging level can be set with the + option (see ). @@ -2260,8 +2237,8 @@ if(s) code_to_be_done_on_match end - Returns true if Nmap was compiled with SSL support, - SSLin NSE + Returns true if Nmap was compiled with + SSL support,SSLin NSE false otherwise. This can be used to avoid sending SSL probes when SSL is not available. @@ -2272,11 +2249,11 @@ if(s) code_to_be_done_on_match end - Returns the verbosity level - verbosityin NSE + Returns the + verbosity levelverbosityin NSE as a non-negative integer. The - verbosity level can be set with the - + verbosity level can be set with the + option (see ). @@ -2454,8 +2431,8 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) - For the provided dnet-style - libdnet + For the provided + dnet-stylelibdnet interface_name, nmap.get_interface_link() returns what kind of link level hardware the interface @@ -2832,10 +2809,9 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) NSE provides script developers with a more powerful option: raw packet network I/O. The greater flexibility comes, however, at the cost of a slightly more complex API. Receiving raw packets is - accomplished via a wrapper around Libpcap - libpcap - inside the Nsock library. - Nsock + accomplished via a wrapper around + Libpcaplibpcap + inside the Nsock library.Nsock In order to keep the capturing efficient it works in a three tiered approach: Opening a device for capturing, registering listeners to it and receiving @@ -2924,8 +2900,8 @@ error_message describes the occurred error. Receiving raw packets is a great feature, but it is also only the half job. Now for sending raw packets: To accomplish this NSE has - access to a wrapper around the dnet library. - libdnet + access to a wrapper around the + dnet library.libdnet Currently NSE has the ability to send raw ethernet frames via the following API: @@ -2990,8 +2966,8 @@ error_message describes the occurred error. Each thread made for a script (e.g. anonFTP.nse) will yield to other scripts whenever it makes a call on network objects (sending/receiving data). Some scripts need finer control over threads' execution. An - example is the whois.nse script which queries whois - whois + example is the whois.nse script which queries + whoiswhois servers for each target. Because many concurrent queries often result in getting one's IP banned for abuse and a query may return additional information for targets other threads are running against, it is useful @@ -3197,8 +3173,7 @@ try(socket:send(result)) Suppose that you are convinced of the power of NSE. How do you go about writing your own script? Let's say that you want to extract information from an identification - server. - auth service + server.auth service Nmap used to have this functionality but it was removed because of inconsistencies in the code base. Fortunately, the protocol identd uses is pretty simple. Unfortunately, it is too @@ -3261,12 +3236,10 @@ port 113, queries the owner of the service on the scanned port and prints it." backslash (‘\’). They must also decide what categories the script belongs to. This script is a good example of a script which cannot be categorized clearly. It is - safe - safe script category + safesafe script category because we are not using the service for anything it was not intended for. On the other hand, it - is intrusive - intrusive script category + is intrusiveintrusive script category because we connect to a service on the target and therefore potentially give out information about us. To solve this dilemma we will place our @@ -3357,8 +3330,7 @@ end send() or receive() we can operate on the network socket. To avoid excessive error checking code we use NSE's - exception handling mechanism. - exceptions in NSE + exception handling mechanism.exceptions in NSE We create a function which will be executed if an error occurs and call this function catch. Using this function we generate @@ -3444,8 +3416,7 @@ end true nature. NSE has been integrated into Nmap's version detection framework to handle these cases. The scripts which extend the version scanner belong to the reserved category - version. - version script category + version.version script category This category cannot be run from the command line. It is only executed if the user has required a version scan. The following listing shows a simple script which @@ -3469,7 +3440,7 @@ license = "Same as Nmap--See http://nmap.org/book/man-legal.html"id script variable -categories = {"version"}categories script variableversion script category +categories = {"version"}categories script variable runlevel = 1.0runlevel script variable @@ -3856,18 +3827,15 @@ also get stored inside the registry. The next phase of NSE initialization is loading the chosen scripts, which are the arguments provided to the - - + option or default, in - case of a default script scan. The string version - version script category + case of a default script scan. The string + versionversion script category is appended, if version detection was enabled. The arguments afterwards are tried to be interpreted as script categories. This is done via a Lua C function in nse_init.cc called entry. - Inside script.db, - script.db - script.db + Inside script.db,script.db for each category of a script, there is a call to Entry. If the category was chosen then the script is loaded. Every argument of @@ -3890,18 +3858,16 @@ also get stored inside the registry. Matching of Scripts to Targets - After the initialization is finished the hostrules - hostrule script variable - and portrules - portrule script variable + After the initialization is finished the + hostruleshostrule script variable + and portrulesportrule script variable are evaluated for each host in the current target group. At this check a list is built which contains the combinations of scripts and the hosts they will run against. It should be noted that the rules of all chosen scripts are -checked against all hosts and their open -open port state -and open|filtered -open|filtered port state +checked against all hosts and their +openopen port state +and open|filteredopen|filtered port state 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 @@ -3921,8 +3887,8 @@ The mainloop function will work on each runlevel grouping of threads in order. Running Scripts - Nmap is able to perform NSE script scanning in parallel - parallelismin NSE + Nmap is able to perform NSE script scanning in + parallelparallelismin NSE by making use of Lua language features. In particular, coroutines offer collaborative multi-threading so scripts can suspend themselves at defined points, and allow other coroutines @@ -3961,8 +3927,7 @@ The mainloop function will work on each runlevel grouping of threads in order. 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 by - bit.c - bit NSE module + bit.cbit NSE module inside the nselib/ subdirectory of Nmap's source tree. bit is a C module already provided by the nselib. C modules @@ -3992,8 +3957,7 @@ The mainloop function will work on each runlevel grouping of threads in order. 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). - x86_64 architecture + case the x86_64-linux platform).x86_64 architecture To our knowledge no such problems occur when linking against already existing shared libraries.