diff --git a/docs/scripting.xml b/docs/scripting.xml index 00543e958..ef627ad50 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -1428,53 +1428,6 @@ if(s) code_to_be_done_on_match end - - IP Operations - ipOps NSE module - - The ipOps module provides some functions for - manipulating IPv4 addresses. The functions reside inside the - ipOps namespace. - - - - - private addressesin NSE - - - - - checks whether an IP address, provided as a string in - dotted-quad notation, is part of the non-routed private IP address - space, as described in RFC 1918. These addresses are the well-known - 10.0.0.0/8, 192.168.0.0/16 and - 172.16.0.0/12 networks. - - - - - - - - - returns the IP address as DWORD value (i.e. the IP a.b.c.d becomes - (((a*256+b)*256+c)*256+d) ) - - - - - - - - - returns 4 numbers corresponding to the fields in dotted-quad notation. - For example, ipOps.get_parts_as_number("192.168.1.1") - returns 192,168,1,1. - - - - - Short Portrules shortport NSE module @@ -1527,159 +1480,6 @@ if(s) code_to_be_done_on_match end - - Functional Programming Style List Operations - listop NSE module - - People used to programming in functional languages, such as Lisp or - Haskell, appreciate their handling of lists very much. The listop module tries to bring much of the functionality from - functional languages to Lua using Lua's central data structure, the table, - as a base for its list operations. Highlights include a map - function applying a given function to each element of a list. - - - - - - - - Returns true if the given list is empty. - - - - - - - - - Returns true if the given value is a list (or rather a table). - - - - - - - - - The provided function is applied to each element of the list - separately. The returned list contains the results of each - function call. For example listop.map(tostring,{1,2,true}) - returns {"1","2","true"}. - - - - - - - - - All of the elements in the list are passed to a call of - function. The result is then returned. For example - listop.apply(math.max,{1,5,6,7,50000}) - yields 50000. - - - - - - - - - Returns a list containing only those elements for which the predicate - returns true. The predicate has to be a function, which takes an - element of the list as argument and the result of which - is interpreted as a Boolean value. If it returns true (or rather - anything besides false and nil) - the argument is appended to the return value of filter. - For example: listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns - {1,2,3,4}. - - - - - - - - - Since a list can itself contain lists as elements, - flatten returns a list which - only contains values that are not themselves - lists. For example: - listop.flatten({1,2,3,"foo",{4,5,{"bar"}}}) returns - {1,2,3,"foo",4,5,"bar"}. - - - - - - - - - Returns a list containing all elements of list1 appended by all - elements of list2. - - - - - - - - - Returns a list containing value1 appended by value2, which may be - of any type. - - - - - - - - - Returns a list containing all elements of the given list in inverted - order. - - - - - - - - - Returns the first element of the given list. - - - - - - - - - Returns the nth (or first if n is omitted) element of the given list. - - - - - - - - - Returns a list containing all elements but the first of the - given list. - - - - - - - - - Returns a list containing all elements but the first n of the - given list, where n is 2 if it is omitted. - - - - - String Buffer Operations strbuf NSE module @@ -1802,185 +1602,6 @@ if(s) code_to_be_done_on_match end - - Buffered Network I/O Helper Functions - match NSE module - - The match module was written to provide - functions which can be used for delimiting data received by the - receive_buf() function from the Network I/O API: - - - - - - - - This is actually a wrapper around NSE's PCRE library exec function (see ), thus - giving script developers the possibility to use regular expressions - for delimiting instead of Lua's string patterns. If you want to get - the data in chunks separated by pattern (which has to be a valid - regular expression), you would write status, val = - sockobj:receive_buf(match.regex("pattern")). - - - - - - - - - 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 - case a script requires more than one - fixed-size chunk, as the unbuffered version - may return more bytes than requested and thus - would require you to do the parsing on your - own. - - - - - - - HTTP Functions - http NSE module - - The http module provides functions for dealing with the client side of the http protocol. - The functions reside inside the http namespace. - The return value of each function in this module is a table with the following keys: - status, status-line, header - and 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. status-line is - the entire status message which includes the HTTP version, - status code and reason phrase. 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. - - - - - - - - Fetches a resource with a GET request. - The first argument is either a string with the hostname or a - table like the host table passed by nmap. The second argument - is either the port number or a table like the port table passed - by nmap. The third argument is the path of the resource. The fourth - argument is a table for further options. The table may have 2 keys: - timeout and header. - timeout is the timeout used for the socket - operations. header is a table with additional - headers to be used for the request. - The function builds the request and calls http.request - - - - - - - - - Sends request to host:port - and parses the answer. - The first argument is either a string with the hostname or a - table like the host table passed by nmap. The second argument - is either the port number or a table like the port table passed - by nmap. SSL is used for the request if either port.service - equals https or port.version.service_tunnel - equals ssl. The third argument is the request. The fourth - argument is a table for further options. You can specify a timeout - for the socket operations with the timeout key. - - - - - - - - - Parses url and calls http.get - with the result. - The second argument is a table for further options. The table may have 2 keys: - timeout and header. - timeout is the timeout used for the socket - operations. header is a table with additional - headers to be used for the request. - - - - - - - - Common Communication Functions - comm NSE module - - The comm module provides functions for common network discovery - tasks such as banner-grabbing and making a quick exchange of data. These functions' - return values are setup for use with exception handling via nmap.new_try(). - exceptions in NSE - - - - These functions can all be passed a table of options, but it's not required. - The relevant indexes for this table are bytes, lines, - proto and timeout. bytes - is used to provide the minimum number of bytes required for a read. lines - does the same, but for the minimum number of lines. If neither are provided, these - functions attempt to read as many bytes as are available. proto - is used to set the protocol to communicate with, defaulting to "tcp" if not provided. - timeout is used to set the socket timeout (see the socket function - set_timeout() for details). - - - - - - - - - This function simply connects to the specified port number on - the specified host and returns any data received. - bool is a Boolean value indicating success. - If bool is true, then the second returned - value is the response from the target host. If bool - is false, an error message is returned as the second value instead - of a response. - - - - - - - - - - This function connects to the specified port number on the - specified host, sends data, then waits for - and returns the response, if any. bool is a - Boolean value indicating success. If bool is - true, then the second returned value is the response from the - target host. If bool is false, an error message - is returned as the second value instead of a response. - - - - - Username/Password Database Functions @@ -2043,69 +1664,6 @@ if(s) code_to_be_done_on_match end - - Data File Parsing Functions - datafiles NSE module - data filesaccess to from NSE - - The datafiles module provides functions for reading and parsing - Nmap's data files (e.g. nmap-protocol, nmap-rpc, - etc.). These functions' return values are setup for use with exception handling via - nmap.new_try(). - - - - - - - - - This function reads and parses Nmap's nmap-protocols - file. bool is a Boolean value indicating success. - If bool is true, then the second returned - value is a table with protocol numbers indexing the protocol - names. If bool is false, an error message - is returned as the second value instead of the table. - - - - - - - - - - This function reads and parses Nmap's nmap-rpc - file. bool is a Boolean value indicating success. - If bool is true, then the second returned - value is a table with RPC numbers indexing the RPC names. If - bool is false, an error message is returned - as the second value instead of the table. - - - - - - - - - - This function reads and parses Nmap's nmap-services - file. bool is a Boolean value indicating success. - If bool is true, then the second returned - value is a table containing two other tables: - tcp{} and udp{}. - tcp{} contains services indexed by TCP port - numbers. udp{} is the same, but for UDP. - You can pass "tcp" or "udp" as an argument to - parse_services() to only get the corresponding - table. If bool is false, an error message is - returned as the second value instead of the table. - - - - - Various Utility Functions diff --git a/nselib/comm.lua b/nselib/comm.lua index d6c991358..c60dc7e51 100644 --- a/nselib/comm.lua +++ b/nselib/comm.lua @@ -1,52 +1,23 @@ ---- The comm module provides functions for common network discovery tasks. --- Banner-grabbing and making a quick exchange of data are some of --- these tasks. These --- functions' return values are setup for use with exception handling --- via nmap.new_try().\n --- \n --- These functions can all be passed a table of options, but it's not --- required. The relevant indexes for this table are bytes, lines, proto --- and timeout. bytes is used to provide the minimum number of bytes required --- for a read. lines does the same, but for the minimum number of lines. --- proto is used to set the protocol to communicate with, defaulting to --- "tcp" if not provided. timeout is used to set the socket timeout (see --- the socket function set_timeout() for details). +--- Common communication functions for network discovery tasks like +-- banner grabbing and data exchange. +-- \n\n +-- The functions in this module return values appropriate for use with +-- exception handling via nmap.new_try(). +-- \n\n +-- These functions may be passed a table of options, but it's not +-- required. The keys for the options table are "bytes", "lines", +-- "proto", and "timeout". "bytes" sets a minimum number of bytes to +-- read. "lines" does the same for lines. "proto" sets the protocol to +-- communicate with, defaulting to "tcp" if not provided. "timeout" sets +-- the socket timeout (see the socket function set_timeout() for +-- details). +-- \n\n +-- If both "bytes" and "lines" are provided, "lines" takes precedence. +-- If neither are given, the functions read as many bytes as possible. -- @author Kris Katterjohn 04/2008 module(... or "comm", package.seeall) --- --- --- The Functions: --- --- get_banner(host, port, [opts]) --- exchange(host, port, data, [opts]) --- --- get_banner() does just what it sounds like it does: connects to the --- host, reads whatever it gives us, and then returns it. --- --- exchange() connects to the host, sends the requested data, reads --- whatever it gives us, and then returns it. --- --- Both of these functions return multiple values so that they can be --- used with exception handling via nmap.new_try(). The second value --- they return is either the response from the host, or the error message --- from one of the previous calls (connect, send, receive*). --- --- These functions can be passed a table of options with the following keys: --- --- bytes: Specifies the minimum amount of bytes are to be read from the host --- lines: Specifies the minimum amount of lines are to be read from the host --- proto: Specifies the protocol to be used with the connect() call --- timeout: Sets the socket's timeout with nmap.set_timeout() --- --- If neither lines nor bytes are specified, the calls attempt to read as many --- bytes as possible. If only bytes is specified, then it only tries to read --- that many bytes. Likewise, it only lines if specified, then it only tries --- to read that many lines. If they're both specified, the lines value is used. --- ------- - -- Makes sure that opts exists and the default proto is there local initopts = function(opts) if not opts then diff --git a/nselib/datafiles.lua b/nselib/datafiles.lua index f16f7db51..498862b9d 100644 --- a/nselib/datafiles.lua +++ b/nselib/datafiles.lua @@ -1,6 +1,10 @@ ---- The datafiles module provides functions for reading and parsing Nmap's --- data files. For example nmap-protocol, nmap-rpc, etc. These functions' --- return values are setup for use with exception handling via nmap.new_try(). +--- Read and parse some of Nmap's data files: nmap-protocol, nmap-rpc, +-- and nmap-services. +-- \n\n +-- The functions in this module return values appropriate for use with +-- exception handling via nmap.new_try(). On success, they return true +-- and the function result. On failure, they return false and an error +-- message. -- @author Kris Katterjohn 03/2008 -- @author jah 08/2008 @@ -10,9 +14,10 @@ local stdnse = require "stdnse" --- --- Holds tables containing captures for common data files, indexed by filename. +-- Capture patterns for common data files, indexed by filename. -- @type table -- @name common_files +-- @see parse_file local common_files = { ["nmap-rpc"] = { [function(ln) return tonumber( ln:match( "^%s*[^%s#]+%s+(%d+)" ) ) end] = "^%s*([^%s#]+)%s+%d+" }, ["nmap-protocols"] = { [function(ln) return tonumber( ln:match( "^%s*[^%s#]+%s+(%d+)" ) ) end] = "^%s*([^%s#]+)%s+%d+" }, @@ -24,11 +29,10 @@ local common_files = { --- --- This function reads and parses Nmap's nmap-protocols file. --- bool is a Boolean value indicating success. If bool is true, then the --- second returned value is a table with protocol numbers indexing the --- protocol names. If bool is false, an error message is returned as the --- second value instead of the table. +-- Read and parse nmap-protocols. +-- \n\n +-- On success, return true and a table mapping protocol numbers to +-- protocol names. -- @return bool, table|err -- @see parse_file parse_protocols = function() @@ -42,11 +46,9 @@ end --- --- This function reads and parses Nmap's nmap-rpc file. bool is a --- Boolean value indicating success. If bool is true, then the second --- returned value is a table with RPC numbers indexing the RPC names. --- If bool is false, an error message is returned as the second value --- instead of the table. +-- Read and parse nmap-rpc. +-- \n\n +-- On success, return true and a table mapping RPC numbers to RPC names. -- @return bool, table|err -- @see parse_file parse_rpc = function() @@ -60,15 +62,14 @@ end --- --- This function reads and parses Nmap's nmap-services file. --- bool is a Boolean value indicating success. If bool is true, --- then the second returned value is a table containing two other --- tables: tcp{} and udp{}. tcp{} contains services indexed by TCP port --- numbers. udp{} is the same, but for UDP. You can pass "tcp" or "udp" --- as an argument to parse_services() to only get the corresponding table. --- If bool is false, an error message is returned as the second value instead --- of the table. --- @param protocol The protocol table to return. +-- Read and parse nmap-services. +-- \n\n +-- On success, return true and a table containing two subtables, indexed +-- by the keys "tcp" and "udp". The tcp table maps TCP port numbers to +-- service names, and the udp table is the same for UDP. You can pass +-- "tcp" or "udp" as an argument to parse_services to get only one of +-- the results tables. +-- @param protocol The protocol table to return ("tcp" of "udp"). -- @return bool, table|err -- @see parse_file parse_services = function(protocol) @@ -86,11 +87,15 @@ end --- --- Generic parsing of datafiles. By supplying this function with a table containing captures to be applied to each line --- of a datafile a table will be returned which mirrors the structure of the supplied table and which contains any captured --- values. A capture will be applied to each line using string.match() and may also be enclosed within a table or a function. --- A function must accept a line as its parameter and should return one value derived from that line. - +-- Read and parse a generic data file. The other parse functions are +-- defined in terms of this one. +-- \n\n +-- If filename is a key in common_files, use the corresponding capture +-- pattern. Otherwise the second argument must be a table of the kind +-- taken by parse_lines. +-- +-- @return A table whose structure mirrors that of the capture table, +-- filled in with captured values. function parse_file( filename, ... ) local data_struct @@ -143,11 +148,16 @@ end --- --- Generic parsing of an array of strings. By supplying this function with a table containing captures to be applied to each value --- of a array-like table of strings a table will be returned which mirrors the structure of the supplied table and which contains any captured --- values. A capture will be applied to each array member using string.match() and may also be enclosed within a table or a function. --- A function must accept an array member as its parameter and should return one value derived from that member. - +-- Generic parsing of an array of strings. +-- +-- @param lines An array of strings to operate on. +-- @param data_struct A table containing capture patterns to be applied +-- to each string in the array. A capture will be applied to each string +-- using string.match() and may also be enclosed within a table or a +-- function. If a function, it must accept a string as its parameter and +-- should return one value derived from that string. +-- @return A table whose structure mirrors that of the capture table, +-- filled in with captured values. function parse_lines( lines, data_struct ) if type( lines ) ~= "table" or #lines < 1 then @@ -192,11 +202,10 @@ end --- --- Reads a file, line by line, into a table. +-- Read a file, line by line, into a table. -- @param file String with the name of the file to read. -- @return Boolean True on success, False on error -- @return Table (array-style) of lines read from the file or error message in case of an error. - function read_from_file( file ) -- get path to file @@ -225,10 +234,9 @@ end --- --- return an array-like table of values captured from each line +-- Return an array-like table of values captured from each line. -- @param lines table of strings containing the lines to process -- @param v_pattern pattern to use on the lines to produce the value for the array - get_array = function( lines, v_pattern ) local ret = {} for _, line in ipairs( lines ) do @@ -246,11 +254,10 @@ end --- --- return an associative array table of index-value pairs captured from each line +-- Return an associative array table of index-value pairs captured from each line. -- @param lines table of strings containing the lines to process -- @param i_pattern pattern to use on the lines to produce the key for the associative array -- @param v_pattern pattern to use on the lines to produce the value for the associative array - get_assoc_array = function( lines, i_pattern, v_pattern ) local ret = {} for _, line in ipairs(lines) do diff --git a/nselib/dns.lua b/nselib/dns.lua index c022cf8a8..cdbf49a26 100644 --- a/nselib/dns.lua +++ b/nselib/dns.lua @@ -1,7 +1,7 @@ module(... or "dns", package.seeall) --- simple DNS library --- packet creation, encoding, decoding, querying +--- Simple DNS library supporting packet creation, encoding, decoding, +-- and querying. require("ipOps") require("stdnse") @@ -33,14 +33,13 @@ err = { --- --- sends repeatedly udp packets to host, --- waiting for an answer ---@param data Data to be sent ---@param host Host to connect to ---@param port Port to connect to +-- Repeatedly sends UDP packets to host, waiting for an answer. +--@param data Data to be sent. +--@param host Host to connect to. +--@param port Port to connect to. --@param timeout Number of ms to wait for a response. ---@param cnt Number of tries ---@return success as boolean and response if available +--@param cnt Number of tries. +--@return success as boolean and response if available. local function sendPackets(data, host, port, timeout, cnt) local socket = nmap.new_socket() socket:set_timeout(timeout) @@ -62,9 +61,9 @@ end --- --- Checks if DNS response packet contains a useful answer ---@param rPkt decoded DNS response packet ---@return True if useful, false if not +-- Checks if a DNS response packet contains a useful answer. +--@param rPkt decoded DNS response packet. +--@return true if useful, false if not. local function gotAnswer(rPkt) -- have we even got answers? if #rPkt.answers > 0 then @@ -93,8 +92,8 @@ end --- --- Tries to find next nameserver with authority --- to get result to query +-- Tries to find the next nameserver with authority to get a result for +-- query. --@param rPkt decoded DNS response packet --@return string or table of next server(s) to query or false local function getAuthDns(rPkt) @@ -124,16 +123,16 @@ local function getAuthDns(rPkt) end --- --- Query DNS servers for a DNS record +-- Query DNS servers for a DNS record. --@param dname wanted domain name entry ---@param options --- dtype wanted DNS record type (default: A) --- host DNS server to be queried (default: DNS servers known to nmap) --- port Port of DNS server to connect to (default: 53) --- tries How often should query try to contact another server (for non-recursive queries) --- retAll Return all answers, not just the first --- retPkt Return the packet instead of using the answer fetching mechanism --- norecurse +--@param options \n +-- dtype wanted DNS record type (default: A).\n +-- host DNS server to be queried (default: DNS servers known to Nmap).\n +-- port Port of DNS server to connect to (default: 53).\n +-- tries How often should query try to contact another server (for non-recursive queries).\n +-- retAll Return all answers, not just the first.\n +-- retPkt Return the packet instead of using the answer fetching mechanism.\n +-- norecurse If true, do not set the recursion (RD) flags.\n --@return Nice answer string by an answer fetcher on success or false and an error code (see: dns.err.*) function query(dname, options) if not options then options = {} end @@ -226,9 +225,9 @@ end --- --- Formats IP for reverse lookup ---@param ip IP address string ---@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa +-- Formats an IP address for reverse lookup. +--@param ip IP address string. +--@return "Domain" style representation of IP as subdomain of in-addr.arpa or ip6.arpa. function reverse(ip) ip = ipOps.expand_ip(ip) if type(ip) ~= "string" then return nil end @@ -262,14 +261,14 @@ function reverse(ip) end --- --- Table for answer fetching functions +-- Table for answer fetching functions. local answerFetcher = {} --- --- answer fetcher for TXT records ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return first entry (or all) treated as TXT +-- Answer fetcher for TXT records. +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return first entry (or all) treated as TXT. answerFetcher[types.TXT] = function(dec, retAll) if not retAll then @@ -284,10 +283,10 @@ answerFetcher[types.TXT] = end --- --- answer fetcher for A records ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return first IP (or all) of response packet +-- Answer fetcher for A records +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return first IP (or all) of response packet. answerFetcher[types.A] = function(dec, retAll) local answers = {} @@ -306,10 +305,10 @@ answerFetcher[types.A] = --- --- answer fetcher for A records ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return Domain entry of first answer RR (or all) in response packet +-- Answer fetcher for CNAME records. +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return Domain entry of first answer RR (or all) in response packet. answerFetcher[types.CNAME] = function(dec, retAll) if not retAll then @@ -324,10 +323,10 @@ answerFetcher[types.CNAME] = end --- --- answer fetcher for A records ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return Domain entry of first answer RR (or all) in response packet +-- Answer fetcher for MX records. +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return Domain entry of first answer RR (or all) in response packet. answerFetcher[types.MX] = function(dec, retAll) if not retAll then @@ -350,10 +349,10 @@ answerFetcher[types.NS] = answerFetcher[types.CNAME] answerFetcher[types.PTR] = answerFetcher[types.CNAME] --- --- answer fetcher for AAAA records ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return first IPv6 (or all) of response packet +-- Answer fetcher for AAAA records. +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return first IPv6 (or all) of response packet. answerFetcher[types.AAAA] = function(dec, retAll) local answers = {} @@ -372,12 +371,12 @@ answerFetcher[types.AAAA] = --- --- Calls answer fetcher for asked type or returns --- error code on a no such name error ---@param dtype DNS resource record type ---@param dec Decoded DNS response ---@param retAll If true return all entries, not just the first ---@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error +-- Calls the answer fetcher for dtype or returns an error code on a no +-- such name error. +--@param dtype DNS resource record type. +--@param dec Decoded DNS response. +--@param retAll If true return all entries, not just the first. +--@return answer by according answer fetcher or packet if none applicable or false and error code if flags indicate an error. function findNiceAnswer(dtype, dec, retAll) if (#dec.answers > 0) then if answerFetcher[dtype] then @@ -393,9 +392,9 @@ end --- --- Encodes the question part of a DNS request ---@param questions Table of questions ---@return Encoded question string +-- Encodes the question part of a DNS request. +--@param questions Table of questions. +--@return Encoded question string. local function encodeQuestions(questions) if type(questions) ~= "table" then return nil end local encQ = "" @@ -411,9 +410,9 @@ local function encodeQuestions(questions) end --- --- Encodes DNS flags to binary digit string ---@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx) ---@return Binary digit string representing flags +-- Encodes DNS flags to a binary digit string. +--@param flags Flag table, each entry representing a flag (QR, OCx, AA, TC, RD, RA, RCx). +--@return Binary digit string representing flags. local function encodeFlags(flags) if type(flags) == "string" then return flags end if type(flags) ~= "table" then return nil end @@ -436,10 +435,10 @@ local function encodeFlags(flags) end --- --- Takes a table representing a DNS packet to encode --- Caution: doesn't encode answer, authority and additional part ---@param pkt Table representing DNS packet, initialized by newPacket() ---@return Encoded DNS packet +-- Takes a table representing a DNS packet to encode. +-- Caution: doesn't encode answer, authority and additional part. +--@param pkt Table representing DNS packet, initialized by newPacket(). +--@return Encoded DNS packet. function encode(pkt) if type(pkt) ~= "table" then return nil end local encFlags = encodeFlags(pkt.flags) @@ -450,11 +449,10 @@ end --- --- Decodes a domain in a DNS packet, --- handles "compressed" data, too ---@param data Complete DNS packet ---@param pos Starting position in packet ---@return Position after decoding and decoded domain +-- Decodes a domain in a DNS packet, Handles "compressed" data too. +--@param data Complete DNS packet. +--@param pos Starting position in packet. +--@return Position after decoding and decoded domain. local function decStr(data, pos) local partlen local parts = {} @@ -477,11 +475,11 @@ end --- --- Decodes questions in a DNS packet ---@param data Complete DNS packet ---@param count Value of question counter in header ---@param pos Starting position in packet ---@return Position after decoding and table of decoded questions +-- Decodes questions in a DNS packet. +--@param data Complete DNS packet. +--@param count Value of question counter in header. +--@param pos Starting position in packet. +--@return Position after decoding and table of decoded questions. local function decodeQuestions(data, count, pos) local q = {} for i = 1, count do @@ -499,8 +497,8 @@ end local decoder = {} --- --- Decodes IP of A record, puts it in entry.ip ---@param entry RR in packet +-- Decodes IP of A record, puts it in entry.ip. +--@param entry RR in packet. decoder[types.A] = function(entry) local ip = {} @@ -510,8 +508,8 @@ decoder[types.A] = end --- --- Decodes IP of AAAA record, puts it in entry.ipv6 ---@param entry RR in packet +-- Decodes IP of AAAA record, puts it in entry.ipv6. +--@param entry RR in packet. decoder[types.AAAA] = function(entry) local ip = {} @@ -525,12 +523,11 @@ decoder[types.AAAA] = end --- --- Decodes ssh fingerprint record, puts it --- in entry.SSHFP as defined in RFC 4255: +-- Decodes SSH fingerprint record, puts it in entry.SSHFP as defined in RFC 4255: -- .algorithm -- .fptype -- .fingerprint ---@param entry RR in packet +--@param entry RR in packet. decoder[types.SSHFP] = function(entry) local _ @@ -541,7 +538,7 @@ decoder[types.SSHFP] = --- --- Decodes SOA record, puts it in entry.SOA.* +-- Decodes SOA record, puts it in entry.SOA.*. --@param entry RR in packet --@param data Complete encoded DNS packet --@param pos Position in packet after RR @@ -563,12 +560,11 @@ decoder[types.SOA] = end --- --- Decodes records which consist only of one domain, --- for example CNAME, NS, PTR. --- Puts result in entry.domain ---@param entry RR in packet ---@param data Complete encoded DNS packet ---@param pos Position in packet after RR +-- Decodes records which consist only of one domain, for example CNAME, +-- NS, PTR. Puts result in entry.domain. +--@param entry RR in packet. +--@param data Complete encoded DNS packet. +--@param pos Position in packet after RR. local function decDomain(entry, data, pos) local np = pos - #entry.data local _ @@ -584,10 +580,10 @@ decoder[types.PTR] = decDomain decoder[types.TXT] = function () end --- --- Decodes MX record, puts it in entry.MX.* ---@param entry RR in packet ---@param data Complete encoded DNS packet ---@param pos Position in packet after RR +-- Decodes MX record, puts it in entry.MX.*. +--@param entry RR in packet. +--@param data Complete encoded DNS packet. +--@param pos Position in packet after RR. decoder[types.MX] = function(entry, data, pos) local np = pos - #entry.data + 2 @@ -599,12 +595,12 @@ decoder[types.MX] = --- --- Decodes returned resource records (answer, authority --- or additional part). ---@param data Complete encoded DNS packet ---@param count Value of according counter in header ---@param pos Starting position in packet ---@return Table of RRs +-- Decodes returned resource records (answer, authority or additional +-- part). +--@param data Complete encoded DNS packet. +--@param count Value of according counter in header. +--@param pos Starting position in packet. +--@return Table of RRs. local function decodeRR(data, count, pos) local ans = {} for i = 1, count do @@ -626,9 +622,9 @@ local function decodeRR(data, count, pos) end --- --- Splits string up into table of single characters ---@param str String to be split up ---@return Table of characters +-- Splits string up into table of single characters. +--@param str String to be split up. +--@return Table of characters. local function str2tbl(str) local tbl = {} for i = 1, #str do @@ -638,9 +634,9 @@ local function str2tbl(str) end --- --- Decodes DNS flags ---@param Flags as binary digit string ---@result Table representing flags +-- Decodes DNS flags. +--@param Flags as binary digit string. +--@result Table representing flags. local function decodeFlags(flgStr) flags = {} flgTbl = str2tbl(flgStr) @@ -661,9 +657,9 @@ local function decodeFlags(flgStr) end --- --- Decodes DNS packet ---@param data Encoded DNS packet ---@result Table representing DNS packet +-- Decodes a DNS packet. +--@param data Encoded DNS packet. +--@result Table representing DNS packet. function decode(data) local pos local pkt = {} @@ -686,8 +682,8 @@ end --- --- Creates new table representing a DNS packet ---@return Table representing a DNS packet +-- Creates a new table representing a DNS packet. +--@return Table representing a DNS packet. function newPacket() local pkt = {} pkt.id = 1 @@ -702,10 +698,10 @@ end --- --- Adds a question to a DNS packet table ---@param pkt Table representing DNS packet ---@param dname Domain name to be asked ---@param dtype RR to be asked +-- Adds a question to a DNS packet table. +--@param pkt Table representing DNS packet. +--@param dname Domain name to be asked. +--@param dtype RR to be asked. function addQuestion(pkt, dname, dtype) if type(pkt) ~= "table" then return nil end if type(pkt.questions) ~= "table" then return nil end diff --git a/nselib/http.lua b/nselib/http.lua index ee7402d6a..50ba38418 100644 --- a/nselib/http.lua +++ b/nselib/http.lua @@ -1,7 +1,7 @@ ---- The http module provides functions for dealing with the client side --- of the http protocol. The functions reside inside the http namespace. +--- Client-side HTTP library. +-- \n\n -- The return value of each function in this module is a table with the --- following keys: status, status-line, header and body. status is a number +-- following keys: status, status-line, header, and 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. status-line is -- the entire status message which includes the HTTP version, status code diff --git a/nselib/ipOps.lua b/nselib/ipOps.lua index 2cbcc30ad..aedfea0af 100644 --- a/nselib/ipOps.lua +++ b/nselib/ipOps.lua @@ -1,4 +1,4 @@ ---- Provides functions for manipulating and comparing IP addresses. The functions reside inside the ipOps namespace. +--- Utility functions for manipulating and comparing IP addresses. -- @copyright See Nmap License: http://nmap.org/book/man-legal.html local type = type @@ -14,7 +14,10 @@ module ( "ipOps" ) --- --- Checks to see if the supplied IP address is part of the following non-internet-routable address spaces: +-- Checks to see if the supplied IP address is part of a non-routable +-- address space. +-- \n\n +-- The non-Internet-routable address spaces known to this function are: -- IPv4 Loopback (RFC3330), -- IPv4 Private Use (RFC1918), -- IPv4 Link Local (RFC3330), @@ -53,8 +56,12 @@ end --- -- Converts the supplied IPv4 address into a DWORD value. --- i.e. the address becomes (((a*256+b)*256+c)*256+d). --- Note: Currently, numbers in NSE are limited to 10^14, consequently not all IPv6 addresses can be represented in base 10. +-- \n\n +-- For example, the address a.b.c.d becomes (((a*256+b)*256+c)*256+d). +-- \n\n +-- Note: IPv6 addresses are not supported. Currently, numbers in NSE are +-- limited to 10^14, consequently not all IPv6 addresses can be +-- represented in base 10. -- @param ip String representing an IPv4 address. Shortened notation is permitted. -- @usage local dword = ipOps.todword( "73.150.2.210" ) -- @return Number corresponding to the supplied IP address (or nil in case of an error). @@ -78,10 +85,12 @@ end --- --- Separates the supplied IP address into its constituent parts and returns them as a table of decimal numbers. --- (e.g. the address 139.104.32.123 becomes { 139, 104, 32, 123 } ) --- @usage local a, b, c, d; --- local t, err = get_parts_as_number( "139.104.32.123" ); +-- Separates the supplied IP address into its constituent parts and +-- returns them as a table of decimal numbers. +-- \n\n +-- For example, the address 139.104.32.123 becomes { 139, 104, 32, 123 }. +-- @usage local a, b, c, d;\n +-- local t, err = get_parts_as_number( "139.104.32.123" );\n -- if t then a, b, c, d = unpack( t ) end -- @param ip String representing an IPv4 or IPv6 address. Shortened notation is permitted. -- @return Array-style Table containing decimal numbers for each part of the supplied IP address (or nil in case of an error). @@ -170,7 +179,9 @@ end --- --- Checks whether the supplied IP address is within the supplied Range of IP addresses if they belong to the same address family. +-- Checks whether the supplied IP address is within the supplied range of IP addresses. +-- \n\n +-- The address and the range must both belong to the same address family. -- @param ip String representing an IPv4 or IPv6 address. Shortened notation is permitted. -- @param range String representing a range of IPv4 or IPv6 addresses in first-last or cidr notation (e.g. "192.168.1.1 - 192.168.255.255" or "2001:0A00::/23"). -- @usage if ipOps.ip_in_range( "192.168.1.1", "192/8" ) then ... @@ -207,6 +218,7 @@ end --- -- Expands an IP address supplied in shortened notation. -- Serves also to check the well-formedness of an IP address. +-- \n\n -- Note: IPv4in6 notated addresses will be returned in pure IPv6 notation unless the IPv4 portion -- is shortened and does not contain a dot - in which case the address will be treated as IPv6. -- @param ip String representing an IPv4 or IPv6 address in shortened or full notation. diff --git a/nselib/listop.lua b/nselib/listop.lua index 123865655..2763672a5 100644 --- a/nselib/listop.lua +++ b/nselib/listop.lua @@ -1,4 +1,5 @@ ---- Functional Programming Style List Operations.\n\n +--- Functional-style list operations. +-- \n\n -- People used to programming in functional languages, such as Lisp -- or Haskell, appreciate their handling of lists very much. The listop -- module tries to bring much of the functionality from functional languages @@ -33,15 +34,15 @@ Functional programming style 'list' operations where 'value' is an lua datatype --]] ---- Determines if the list is empty. +--- Returns true if the given list is empty. -- @param l A list. -- @return boolean function is_empty(l) return #l == 0 and true or false; end ---- Determines if l is a list (rather, a table). --- @param l A list. +--- Returns true if the given value is a list (or rather a table). +-- @param l Any value. -- @return boolean function is_list(l) return type(l) == 'table' and true or false; @@ -49,6 +50,9 @@ end --- Calls f for each element in the list. The returned list contains -- the results of each function call. +-- \n\n +-- For example, listop.map(tostring,{1,2,true}) returns +-- {"1","2","true"}. -- @param f The function to call. -- @param l A list. -- @return List @@ -61,6 +65,8 @@ function map(f, l) end --- Calls the function with all the elements in the list as the parameters. +-- \n\n +-- For example, listop.apply(math.max,{1,5,6,7,50000}) yields 50000. -- @param f The function to call. -- @param l A list. -- @return Results from f. @@ -68,12 +74,14 @@ function apply(f, l) return f(unpack(l)) end ---- Returns a list containing only those elements for which the predicate --- returns true. The predicate has to be a function, which takes an element --- of the list as argument and the result of which is interpreted as a --- Boolean value. If it returns true (or rather anything besides false --- and nil) the argument is appended to the return value of filter. For --- example: listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns {1,2,3,4}. +--- Returns a list containing only those elements for which a predicate +-- function returns true. +-- \n\n +-- The predicate has to be a function taking one argument and returning +-- a Boolean. If it returns true (or rather anything besides false and +-- nil) the argument is appended to the return value of filter. For +-- example, listop.filter(isnumber,{1,2,3,"foo",4,"bar"}) returns +-- {1,2,3,4}. -- @param f The function. -- @param l The list. -- @return List @@ -101,7 +109,7 @@ function cdr(l) return {unpack(l, 2)} end ---- Fetch element x from l. +--- Fetch element at index x from l. -- @param l The List. -- @param x Element index. -- @return Element x or 1. @@ -109,7 +117,7 @@ function ncar(l, x) return l[x or 1]; end ---- Fetch all elements following the x or the first in a new List. +--- Fetch all elements following the element at index x or the first. -- @param l The List. -- @param x Element index. -- @return List @@ -149,8 +157,11 @@ function reverse(l) return results end ---- Return a flattened version of the List, l. All lists within l are --- replaced by its contents. +--- Return a flattened version of a list. The flattened list contains +-- only non-list values. +-- \n\n +-- For example, listop.flatten({1,2,3,"foo",{4,5,{"bar"}}}) returns +-- {1,2,3,"foo",4,5,"bar"}. -- @param l The list to flatten. -- @return List function flatten(l) diff --git a/nselib/match.lua b/nselib/match.lua index 644acde14..671074b8c 100644 --- a/nselib/match.lua +++ b/nselib/match.lua @@ -1,5 +1,7 @@ ---- Provides functions which can be used for delimiting data received --- by receive_buf() function in the Network I/O API. +--- Buffered network I/O helper functions. +-- \n\n +-- The functions in this module can be used for delimiting data received +-- by the receive_buf function in the Network I/O API. --@copyright See nmaps COPYING for licence module(... or "match", package.seeall) @@ -14,13 +16,13 @@ require "pcre" -- sock:receive_bytes(80) - i.e. it returns -- exactly 80 bytes and no more ---- This is actually a wrapper around NSE's PCRE library exec function, --- thus giving script developers the possibility to use regular expressions --- for delimiting instead of Lua's string patterns. If you want to get the --- data in chunks separated by pattern (which has to be a valid regular --- expression), you would write: --- status, val = sockobj:receive_buf(match.regex("pattern")). +--- Return a function that allows delimiting with a regular expression. +-- \n\n +-- This function is a wrapper around the exec function of the pcre +-- library. It purpose is to give script developers the ability to use +-- regular expressions for delimiting instead of Lua's string patterns. -- @param The regex. +-- @usage sock:receivebuf(regex("myregexpattern")) regex = function(pattern) local r = pcre.new(pattern, 0,"C") @@ -30,12 +32,15 @@ regex = function(pattern) end end ---- 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 case a --- script requires more than one fixed-size chunk, as the unbuffered --- version may return more bytes than requested and thus would require --- you to do the parsing on your own. +--- Return a function that allows delimiting at a certain number of bytes. +-- \n\n +-- This function can be used to get a buffered version of +-- sockobj:receive_bytes(n) in case a script requires more than one +-- fixed-size chunk, as the unbuffered version may return more bytes +-- than requested and thus would require you to do the parsing on your +-- own. -- @param num Number of bytes. +-- @usage sock:receivebuf(numbytes(80)) numbytes = function(num) local n = num return function(buf)