diff --git a/docs/refguide.xml b/docs/refguide.xml index 123a1781d..d6dd8a327 100644 --- a/docs/refguide.xml +++ b/docs/refguide.xml @@ -2035,28 +2035,36 @@ 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/; +Runs a script scan (like ) using the comma-separated list of +script categories, individual scripts, or directories containing +scripts, rather than the default set. Nmap first tries to interpret the +arguments as categories, then (if that fails) as files or +directories. A script or directory of scripts may be specified as an +absolute or relative path. Absolute paths are used as +supplied. Relative paths are searched for in the following places +until found:data filesdirectory search orderscripts, location of +--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. - +./. A scripts/ subdirectory +is also tried in each of these. If a directory is specified and found, Nmap loads all NSE -scripts (any filenames with the nse extension) from that -directory. They must have the filename extension -nse. Nmap does not recurse into subdirectories to -find scripts. When individual file names are specified, the file -extension does not have to be nse. - +scripts (any filenames ending with .nse) from that +directory. Filenames without the nse extension are +ignored. Nmap does not search recursively into subdirectories to find +scripts. If individual file names are specified, the file extension +does not have to be nse. Nmap scripts are stored in a scripts -subdirectory of the Nmap data directory -by default. Scripts are indexed in a database stored in -scripts/script.db. The database lists all of the -scripts in each category. A single script may be in several -categories. +subdirectory of the Nmap data directory by default (see +). For efficiency, scripts are indexed in +a database stored +in scripts/script.db.script.db +which lists the category or categories in which each script belongs. +Give the argument all to execute all scripts in the +Nmap script database. Malicious scripts are not run in a sandbox and thus could damage your system or invade your privacy. Never run scripts from third parties unless you trust the authors or have carefully audited the scripts yourself. @@ -2111,15 +2119,16 @@ script knows about its special argument. - - updates the script database which stores a mapping from - category tags to filenames. The database is a Lua script which is - interpreted once to choose a set of scripts from the categories - provided to the argument. - It should be run if you have changed the categories - field of a script, if you have added new scripts or if you have - removed scripts from the scripts/ directory. - + This option updates the script database found + in scripts/script.db which is used by + Nmap to determine the available default scripts and + categories. It is only necessary to update the database if + you have added or removed NSE scripts from the + default scripts directory or if you + have changed the categories of any script. This option is + generally used by + itself: nmap --script-updatedb. + diff --git a/docs/scripting.xml b/docs/scripting.xml index 551d90408..ea50faff4 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -142,12 +142,12 @@ The reference manual is also on the other hand, run no more than once against each target IP and produce results below the port table. shows a typical script scan. Examples of - service scripts producing output are Stealth SSH + service scripts producing output are: Stealth SSH version, which tricks some SSH servers into divulging version information without logging the attempt as they normally - would, Service Owner, which connects to open + would; Service Owner, which connects to open ports, then performs a reverse-identd query to determine what - username it is running under, and HTML Title, + username each 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 @@ -236,8 +236,9 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds + These are scripts that cannot be classified in the - "safe" category because the risks are too high that they + safe category because the risks are too high that they will crash the target system, use up significant resources on the target host (such as bandwidth or CPU time), or otherwise be perceived as malicious by the target's @@ -251,7 +252,7 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds - These scripts test if the target platform is + These scripts test whether the target platform is infected by malware or backdoors. @@ -263,13 +264,15 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds - This category cannot be selected explicitly. It is only - run if - was supplied. The scripts in this category are an - extension to the version detection service. Their output - cannot be distinguished from version detection output - and they do not produce script scanning - output. + + The scripts in this category are an extension to the + version detection option and cannot be selected + explicitly. They are selected to run only if version + detection () was requested. Their + output cannot be distinguished from version detection + output and they do not produce service or host script + results. + @@ -292,7 +295,7 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds These scripts check for specific known vulnerabilities and - generally only report results if it is found. + generally only report results if they are found. @@ -314,55 +317,15 @@ Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds These scripts are the default set and are run when - using , or - without any arguments. This category can also be specified - explicitly like any other using . - Don't be fooled into thinking that just because these scripts - are run by default that they are all completely unobtrusive: - these scripts should not be run against target networks without - permission. + using , + or without any arguments. This + category can also be specified explicitly like any other + using . - - Arguments to Scripts - script arguments - - You can pass arguments to NSE scripts via the - option. The script-arguments generally are - name-value pairs, which are provided to the script as a Lua table called - args inside the nmap.registry with - the names as keys for the corresponding values. The values can either be - strings or tables. Subtables can be used to pass arguments to - scripts with a finer granularity (e.g. pass different usernames for - different scripts). A typical nmap invocation with script arguments may - look like: - - -example of -example of - -$ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com} - - - - which would result in the Lua table: - - -{user="foo",pass="bar",anonFTP={pass="nobody@foobar.com"}} - - - You could therefore access the username ("foo") - 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, otherwise scripts won't know where to - retrieve their arguments. - - Command-line Arguments @@ -390,39 +353,36 @@ $ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com} - -Runs a script scan (like ) with the comma separated -list of scripts you have chosen rather than the defaults. Specifically, -the list can contain 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:data filesdirectory search orderscripts, location of +Runs a script scan (like ) using the comma-separated list of +script categories, individual scripts, or directories containing +scripts, rather than the default set. Nmap first tries to interpret the +arguments as categories, then (if that fails) as files or +directories. A script or directory of scripts may be specified as an +absolute or relative path. Absolute paths are used as +supplied. Relative paths are searched for in the following places +until found:data filesdirectory search orderscripts, location of --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. - +is also tried in each of these. If a directory is specified and found, Nmap loads all NSE scripts (any filenames ending with .nse) from that -directory. They must have the filename extension -nse. Nmap does not recurse into subdirectories to -find scripts. When individual file names are specified, the file -extension does not have to be nse. - +directory. Filenames without the nse extension are +ignored. Nmap does not search recursively into subdirectories to find +scripts. If individual file names are specified, the file 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 -The database lists all of the -scripts in each category. A single script may be in several -categories. +subdirectory of the Nmap data directory by default (see +). For efficiency, scripts are indexed in +a database stored +in scripts/script.db.script.db +which lists the category or categories in which each script belongs. +Give the argument all to execute all scripts in the +Nmap script database. Malicious scripts are not run in a sandbox and thus could damage your system or invade your privacy. Never run scripts from third parties unless you trust the authors or have carefully audited the scripts yourself. @@ -467,21 +427,17 @@ categories. - This option is only useful if you have added or - removed NSE scripts from the default - scripts directory, or if you have - changed any of the scripts' categories - fields. This field contains categories such as - safe and discovery - which the script belongs to. Categories may be - specified with the option. For - efficiency reasons, NSE generates a - script.db - file which maps - categories to the scripts they contain. If you changed - tag directives or added/removed scripts, run - nmap --script-updatedb. - + + This option updates the script database found + in scripts/script.db which is used by + Nmap to determine the available default scripts and + categories. It is only necessary to update the database if + you have added or removed NSE scripts from the + default scripts directory or if you + have changed the categories of any script. This option is + generally used by + itself: nmap --script-updatedb. + @@ -508,15 +464,55 @@ categories. + + + Arguments to Scripts + script arguments + + You can pass arguments to NSE scripts via the + option. The script-arguments generally are + name-value pairs, which are provided to the script as a Lua table called + args inside the nmap.registry with + the names as keys for the corresponding values. The values can either be + strings or tables. Subtables can be used to pass arguments to + scripts with a finer granularity (e.g. pass different usernames for + different scripts). A typical nmap invocation with script arguments may + look like: + + +example of +example of + +$ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com} + + + + which would result in the Lua table: + + +{user="foo",pass="bar",anonFTP={pass="nobody@foobar.com"}} + + + You could therefore access the username ("foo") + 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, otherwise scripts won't know where to + retrieve their arguments. + + + + Usage Examples - Simple script scan. + A simple script scan using the default set of scripts example of - $ nmap -sC hostname + $ nmap -sC example.com @@ -526,16 +522,24 @@ categories. example of example of - $ nmap --script=./showSSHVersion.nse --script-trace hostname + $ nmap --script=./showSSHVersion.nse --script-trace example.com + + + + + All scripts in a subdirectory named mycustomscripts in addition to all of Nmap's included scripts which are in the safe category. + + + + $ nmap --script=mycustomscripts,safe example.com Script Format - NSE scripts consist of four descriptive fields, a port or host rule defining when the script should be executed, and an action block containing the actual script instructions. All six of these are Lua variables that are assigned to. Their names must be lowercase as shown here. + NSE scripts consist of six descriptive fields along with either a port or host rule defining when the script should be executed and an action block containing the actual script instructions. Values can be assigned to these fields just as you would assign any other Lua variables. Their names must be lowercase as shown here. - <literal>id</literal> Field “id” script variable @@ -552,15 +556,27 @@ categories. <literal>description</literal> Field “description” script variable - - The description describes what the script is testing for and - any critical notes the user must be aware of. A good - example is this user contributed recursive DNS script - description Checks whether a nameserver on UDP port 53 - allows queries for third party names. It is expected that - recursion will be enabled on your own internal - nameserver. - + The description field describes what the script is testing + for and any critical notes the user must be aware of. A good + example is this description from a user-contributed recursive + DNS script: Checks whether a nameserver on UDP port 53 + allows queries for third party names. It is expected that + recursion will be enabled on your own internal + nameserver. + + + + <literal>categories</literal> Field + “category” script variable + + The categories field defines one or + more categories to which a script belongs (see + ). The categories are case-insensitive and may be specified in any order. They are listed in an array-like Lua table as in this example: + + +categories = {"default", "discovery", "safe"} + + @@ -582,7 +598,7 @@ categories. The license field helps ensure that we have legal permission to distribute all the scripts which come with Nmap. All of those scripts currently use the standard Nmap license - (described in ). They + (described in ). They include the following line: @@ -624,38 +640,33 @@ that. rules in NSE“portrule” and “hostrule” - There are two types of rules: host rules - which run only once against a target IP and port - rules which run against individual ports on a - target. A rule is a Lua function which takes a host and a - port table as arguments and must return a Boolean value. If the rule - 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 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 - matched using a host rule, then the port table is absent (nil). - Example rules are shown in - . +Nmap uses the script rules to determine whether a script should be run +against a target. A script contains either a port +rule, which governs which ports of a target the scripts may +run against, or a host rule, which specifies that +the script should be run only once against a target IP and only if +certain conditions are met. A rule is a Lua function that returns +either true or false. The +script action is only performed if the rule +evaluates to true. The host rule accepts a host +table as an argument and may test, for example, the IP address or +hostname of the target. A port rule accepts both host and port tables +as arguments for any TCP or UDP port in either the +openopen port state, +open|filteredopen|filtered port state, +or unfilteredunfiltered port state port states. Port rules generally test factors such as the port number, port state, or listening service name in deciding whether to run against a port. Example rules are shown in . + Action “action” script variable - The action is the heart of an NSE script. It contains all of - the instructions to be executed when the script's port or host - rule triggers. It is a Lua function which can return either - nil or a string. If a string is returned, - it is printed along with the script ID in (if it is a service - script) or below (if it is a host script) the Nmap port table. - If the script returns nil, no output is - produced. For an - example of an NSE action refer to . +The action is the heart of an NSE script. It contains all of the +instructions to be executed when the script's port or host rule +triggers. It is a Lua function which accepts the same arguments as the +rule and can return either nil or a string. If a string is returned by a service script, the string and script ID are printed in the Nmap port table output. A string returned by a host script is printed below the port table. No output is produced if the +script returns nil. For an example of an NSE +action refer to . @@ -707,7 +718,7 @@ that. efforts to design a security auditing language from scratch which have resulted in well-known awkward solutions. It was clear from the beginning that we would not go down this - road. For a while the Guile scheme interpreter was considered + road. For a while the Guile Scheme interpreter was considered but the preference drifted towards Elk in favor of its more liberal license. But parallelizing Elk scripts would have been difficult. In addition, the subset of Nmap users familiar with @@ -775,7 +786,7 @@ that. - Returns the one's complement of a. + Returns the one's complement of a. @@ -786,7 +797,7 @@ that. Returns the bitwise and of the - w's. + w variables. @@ -796,7 +807,7 @@ that. - Returns the bitwise or of the w's. + Returns the bitwise or of the w variables. @@ -807,8 +818,7 @@ that. - Returns the bitwise xor of the - w's. + Returns the bitwise xor of the w variables. @@ -818,7 +828,7 @@ that. - Returns a shifted left b places—padded with zeros. + Returns a shifted left b places—padded with zeros. @@ -828,7 +838,7 @@ that. - Returns a shifted logically right b places. + Returns a shifted logically right b places. @@ -838,7 +848,7 @@ that. - Returns a shifted arithmetically right b places. + Returns a shifted arithmetically right b places. @@ -848,7 +858,7 @@ that. - Returns the integer remainder of a divided by b. + Returns the integer remainder of a divided by b. @@ -1068,7 +1078,7 @@ that. returned value is a table which contains false in the positions where the pattern did not match. If named sub-patterns were - used the table also contains substring matches keyed + used, the table also contains substring matches keyed by their sub-pattern name. Should no match be found the function returns nil. The second and third arguments are optional. The second @@ -1209,7 +1219,7 @@ if(s) code_to_be_done_on_match end determined by Nmap's version scan or (if no version scan information is available) the service assigned to the port in nmap-services - (i.e. "http" for TCP port 80). + (e.g. "http" for TCP port 80). @@ -1531,7 +1541,7 @@ if(s) code_to_be_done_on_match end - Takes a number as argument and returns that + Takes a number as its argument and returns that many bytes. It can be used to get a buffered version of sockobj:receive_bytes(n) in @@ -1553,12 +1563,20 @@ if(s) code_to_be_done_on_match end The functions reside inside the http namespace. The return value of each function in this module is a table with the following keys: status, header and body. - status is the status code of the http request - In case of an error status is nil. header - is a table with the headers received from the server. The header names are - lower-cased and multiple headers of the same name are concatenated with comma. - body holds a string with the request body. - + + status is a number representing the HTTP + status code returned in response to the HTTP request. In case + of an unhandled error, status + is nil. The header value + is a table containing key-value pairs of HTTP headers received + in response to the request. The header names are in lower-case + and are the keys to their corresponding header values + (e.g. header.location = + "http://nmap.org/"). Multiple headers of the same + name are concatenated and separated by + commas. The body value is a string + containing the body of the HTTP response. + @@ -2032,7 +2050,7 @@ if(s) code_to_be_done_on_match end - The hosts IP as 4 byte long binary value. + The target host's IPv4 address as 4 byte long binary value. @@ -2040,7 +2058,7 @@ if(s) code_to_be_done_on_match end - Our hosts IP as 4 byte long binary value. + Our host's (running Nmap) source IPv4 address as 4 byte long binary value. @@ -2127,7 +2145,7 @@ if(s) code_to_be_done_on_match end name_confidence - Evaluates how confident the version detection is about the accuracy of name, from one (least confident) to 10. + Evaluates how confident the version detection is about the accuracy of name, from 1 (least confident) to 10. @@ -2150,18 +2168,14 @@ if(s) code_to_be_done_on_match end rpc_status + Contains a string value of good_prog if - we were able to determine the program number of an RPC - service listening on the port, unknown - if the port appears to be RPC but we couldn't determine the - program number, not_rpc if the port - doesn't appear be RPC, or untested if we - haven't checked for RPC status. The - rpc_program, - rpc_lowver, and - rpc_highver variables are nil unless - rpc_status is - good_prog. + we were able to determine the program number of an RPC service + listening on the port, unknown if the port + appears to be RPC but we couldn't determine the program + number, not_rpc if the port doesn't appear be + RPC, or untested if we haven't checked for RPC + status. @@ -2331,17 +2345,19 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) - - The set_port_state() call takes a host table, - a port table, and a port state (open or - closed). With this method the final port - state can be changed. This is useful when Nmap detects a port as - open|filtered but the script successfully connects to it. In this - case the port state can be set to open. Note - that the port.state value, which was passed - to the script's action function will not be changed - by this call. - + + +The set_port_state() call takes a host table, +a port table, and a port state (open +or closed). Using this method the final port state, +reflected in Nmap's results, can be changed for a target. This is +useful when Nmap detects a port as open|filtered +(i.e. unable to determine which), but the script successfully connects +to that port. In this case the script can set the port state +to open. Note that the port.state value, which was +passed to the script's action function will not be changed by this +call. + @@ -2814,9 +2830,8 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) The more general the packet hash computing function is kept, the more scripts may receive the packet and proceed with their execution. To use the packet capturing inside your script you have to - create (and afterwards close) a socket with - nmap.newsocket() - (or socket_object:close() respectively)—just + create a socket with + nmap.newsocket() and later close the socket with socket_object:close()—just like with the connection-based network I/O. A more detailed description of the functions for packet capturing follows: @@ -2832,9 +2847,9 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) The pcap_open() call opens the socket for packet capturing. The parameters are: -device—the dnet-style interface name of the device you want to capture from. +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. +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 bpf—a string describing a Berkeley packet filter expression (like those provided to tcpdump) @@ -2863,10 +2878,10 @@ nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"}) Receives a captured packet. If successful, the return values are: -status—a Boolean with the value true. -packet_len—the length of the captured packet (note, that you could have received less data if the snaplen parameter was smaller than the packet length) +status—a Boolean with the value true +packet_len—the length of the captured packet which was received (this may be smaller than the actual packet length since packets are truncated when the Libpcap snaplen parameter is smaller than the total packet length) l2_data—data from the second OSI layer (e.g. ethernet headers) -l3_data—data from the third OSI layer (e.g. IPv4 headers). +l3_data—data from the third OSI layer (e.g. IPv4 headers) Should an error or timeout occur, while waiting for a packet the @@ -2989,7 +3004,7 @@ error_message describes the occurred error. except nil, booleans, and numbers. The returned function allows you to lock, try to lock, and - release the mutex. It's first and only parameter is either: + release the mutex. Its first and only parameter must be one of the following: @@ -3020,10 +3035,12 @@ error_message describes the occurred error. - "running"—Returns the thread locked - on the mutex or nil. This - should only be used for debugging as it interferes - with finished threads from being collected. + "running"—Returns an + identification string for a thread locked on the + mutex or nil if the mutex is not + locked. This should only be used for debugging as it + interferes with finished threads from being + collected. @@ -3190,17 +3207,19 @@ try(socket:send(result)) The Head - The head of the script is essentially its meta - information. This includes the fields - id, description, - author, license and - categories. We are not going to change the - run level for now. The id of a script - should uniquely identify it. If it is absent, the path to the - script will be used as an id. We recommend to choose an id - which concisely identifies the purpose of the script, since - the ID is printed before the script's results in Nmap output. + + The head of the script is essentially its meta information. This + includes the + fields: id, description, categories, runlevel, author + and license. We are not going to change the + run level, or worry about the author and license fields for now. + The id of a script should uniquely identify + it. If it is absent, the path to the script will be used as an + id. We recommend to choose an id which concisely identifies the + purpose of the script, since the ID is printed before the + script's results in Nmap output. + “Service Owner” script “id” script variable @@ -3325,23 +3344,7 @@ end catch. Using this function we generate a try function. The try function will call the catch function - whenever there is an error condition in the tried block. Note - that we could have ignored the last two return values - of client_service:get_info() like this: - - -local localip, localport = client_service:get_info() - - This would have sufficed because we know that the remote port is - stored in port.number. - - In this example we - prefer not to tell the user if the query resulted in an - error. To inform users of failed - identification queries, simply uncomment the corresponding - line. It is necessary that we assign the variable owner - a nil value because returning nil - is the only way to tell the script engine to suppress script output. + whenever there is an error condition in the tried block. @@ -3386,6 +3389,18 @@ return owner end + +Note that because we know that the remote port is stored +in port.number, we could have ignored the last two +return values of client_service:get_info() like +this: + + +local localip, localport = client_service:get_info() + + +In this example we avoided telling the user if the service responded with an error. Instead we commented that line out and assigned nil to the owner variable. NSE scripts generally only return messages when they succeed. + @@ -3559,6 +3574,13 @@ we want to use shorter port rules. require "shortport" +We want to run the script against the finger service. So we +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 @@ -3592,7 +3614,7 @@ a call to nmap.new_try() local try = nmap.new_try(err_catch()) -The script sets a timeout of 5000, which is equivalent to 50 +The script sets a timeout of 5000, which is equivalent to 5 seconds. Should any operation require more time we'll receive a TIMEOUT error message. @@ -3600,36 +3622,30 @@ seconds. Should any operation require more time we'll receive a socket:set_timeout(5000) -For actually using exception handling we need to wrap calls to -functions, which may return an error inside -try() +To make use of the exception handling we need to wrap calls to those functions which might return an error, inside try() try(socket:connect(host.ip, port.number, port.protocol)) try(socket:send("\n\r")) -The call to receive_lines() is not wrapped in -try(), because we don't want to abort the script -just because we didn't receive the data we expected. Note that there -is less data than requested (100 lines), we still receive it and the -status is true —consequent calls would yield -a false status. +The call to receive_lines() is not wrapped +in try(), because we don't want to abort the script +just because we didn't receive the data we expected. Note that if +there is less data than requested (100 lines), we will still receive +it and the status will be true—subsequent +calls would yield a false status. status, results = socket:receive_lines(100) socket:close() -The script returns a string only if we got the data we -wanted, otherwise nil is returned (automatically, since -scripts return one result). +The script returns a string if the call to receive_lines() was successful, otherwise it returns nil. - if not(status) then - return results + return results end -end