diff --git a/nselib/amqp.lua b/nselib/amqp.lua index 5804ba608..461792afa 100644 --- a/nselib/amqp.lua +++ b/nselib/amqp.lua @@ -190,8 +190,8 @@ AMQP = { end, --- Performs the AMQP handshake and determines - -- o The AMQP protocol version - -- o The server properties/capabilities + -- * The AMQP protocol version + -- * The server properties/capabilities -- -- @return status, true on success, false on failure -- @return error string containing error message if status is false diff --git a/nselib/asn1.lua b/nselib/asn1.lua index f456881a2..6b105ccc3 100644 --- a/nselib/asn1.lua +++ b/nselib/asn1.lua @@ -41,8 +41,9 @@ ASN1Decoder = { return o end, - --- Tells the decoder to stop if it detects an error while decoding - -- this should probably be the default, but some scripts depend on being + --- Tells the decoder to stop if it detects an error while decoding. + -- + -- This should probably be the default, but some scripts depend on being -- able to decode stuff while lacking proper ASN1 decoding functions. -- @name ASN1Decoder.setStopOnError -- @param val boolean, true if decoding should stop on error, @@ -324,6 +325,7 @@ ASN1Encoder = { end, --- Registers the base ASN.1 Simple types encoders + -- -- * boolean -- * integer (Lua number) -- * string @@ -446,8 +448,8 @@ ASN1Encoder = { } ---- --- Converts a BER encoded type to a numeric value +--- Converts a BER encoded type to a numeric value +-- -- This allows it to be used in the encoding function -- -- @param class number - see BERCLASS diff --git a/nselib/bittorrent.lua b/nselib/bittorrent.lua index 2bf648514..36d82c05b 100644 --- a/nselib/bittorrent.lua +++ b/nselib/bittorrent.lua @@ -695,6 +695,7 @@ Torrent = end, --- Runs the three threads which do a DHT discovery of nodes and peers. + -- -- The default timeout for this discovery is 30 seconds but it can be -- set through the timeout argument. dht_peers = function(self, timeout) @@ -756,6 +757,7 @@ Torrent = end, --- Parses self.buffer, fills self.tor_struct, self.info_buf + -- -- This function is similar to the bdecode function but it has a few -- additions for calculating torrent file specific fields parse_buffer = function(self) @@ -1026,9 +1028,10 @@ Torrent = if size == 0 then return false end end, - --- Calculates the info hash using self.info_buf. The info_hash value - -- is used in many communication transactions for identifying the file - -- shared among the bittorrent peers + --- Calculates the info hash using self.info_buf. + -- + -- The info_hash value is used in many communication transactions for + -- identifying the file shared among the bittorrent peers calc_info_hash = function(self) local info_hash = openssl.sha1(self.info_buf) self.info_hash_url = url.escape(info_hash) @@ -1142,9 +1145,10 @@ Torrent = return true end, - --- Gets the peers from udp trackers when supplied the URL of the tracker - -- First we establish a connection to the udp server and then we can request peers - -- for a good specification refer to: + --- Gets the peers from udp trackers when supplied the URL of the tracker. + -- + -- First we establish a connection to the udp server and then we can request + -- peers. For a good specification refer to: -- http://www.rasterbar.com/products/libtorrent/udp_tracker_protocol.html udp_tracker_peers = function(self, tracker) local host, port = tracker:match("^udp://(.-):(.+)") diff --git a/nselib/dhcp.lua b/nselib/dhcp.lua index e6df6cbec..37c37a4a7 100644 --- a/nselib/dhcp.lua +++ b/nselib/dhcp.lua @@ -471,14 +471,16 @@ function dhcp_build(request_type, ip_address, mac_address, options, request_opti return true, packet end ----Parse a DHCP packet (either a request or a response) and return the results as a table. The --- table at the top of this function (actions) defines the name of each field, as --- laid out in rfc2132, and the function that parses it. +---Parse a DHCP packet (either a request or a response) and return the results +-- as a table. +-- +-- The table at the top of this function (actions) defines the +-- name of each field, as laid out in rfc2132, and the function that parses it. -- -- In theory, this should be able to parse any valid DHCP packet. -- ---@param data The DHCP packet data. Any padding at the end of the packet will be ignored (by default, --- DHCP packets are padded with \x00 bytes). +--@param data The DHCP packet data. Any padding at the end of the packet will +-- be ignored (by default, DHCP packets are padded with \x00 bytes). function dhcp_parse(data, transaction_id) local pos = 1 local result = {} diff --git a/nselib/dns.lua b/nselib/dns.lua index de47e3026..dbe54ecf2 100644 --- a/nselib/dns.lua +++ b/nselib/dns.lua @@ -1414,6 +1414,7 @@ end --- -- Adds an client-subnet payload to the OPT packet +-- -- implementing http://tools.ietf.org/html/draft-vandergaast-edns-client-subnet-00 -- @param pkt Table representing DNS packet. -- @param Z Table of Z flags. Only DO is supported. @@ -1441,8 +1442,10 @@ function addNSID (pkt,Z) end --- --- Adds an OPT RR to a DNS packet's additional section. Only the table of Z --- flags is supported (i.e., not RDATA). See RFC 2671 section 4.3. +-- Adds an OPT RR to a DNS packet's additional section. +-- +-- Only the table of Z flags is supported (i.e., not RDATA). See RFC 2671 +-- section 4.3. -- @param pkt Table representing DNS packet. -- @param Z Table of Z flags. Only DO is supported. function addOPT(pkt, Z, opt) diff --git a/nselib/formulas.lua b/nselib/formulas.lua index f26f57bd1..1489fe3ad 100644 --- a/nselib/formulas.lua +++ b/nselib/formulas.lua @@ -17,6 +17,7 @@ local table = require "table" _ENV = stdnse.module("formulas", stdnse.seeall) --- Calculate the entropy of a password. +-- -- A random password's information entropy, H, is given by the formula: H = L * -- (logN) / (log2), where N is the number of possible symbols and L is the -- number of symbols in the password. Based on @@ -94,6 +95,7 @@ local CHI2_CDF = { } --- Checks whether a sample looks random +-- -- Because our sample is so small (only 16 bytes), do a chi-square -- goodness of fit test across groups of 2, 4, and 8 bits. If using only -- 8 bits, for example, any sample whose bytes are all different would diff --git a/nselib/http.lua b/nselib/http.lua index 1169c2818..340520f71 100644 --- a/nselib/http.lua +++ b/nselib/http.lua @@ -1443,24 +1443,28 @@ local function get_redirect_ok(host, port, options) end end ----Fetches a resource with a GET request and returns the result as a table. This is a simple --- wrapper around generic_request, with the added benefit of having local caching --- and support for HTTP redirects. Redirects are followed only if they pass all the --- validation rules of the redirect_ok function. This function may be overridden by supplying --- a custom function in the redirect_ok field of the options array. The default +---Fetches a resource with a GET request and returns the result as a table. +-- +-- This is a simple wrapper around generic_request, with the added +-- benefit of having local caching and support for HTTP redirects. Redirects +-- are followed only if they pass all the validation rules of the redirect_ok +-- function. This function may be overridden by supplying a custom function in +-- the redirect_ok field of the options array. The default -- function redirects the request if the destination is: -- * Within the same host or domain -- * Has the same port number -- * Stays within the current scheme -- * Does not exceed MAX_REDIRECT_COUNT count of redirects -- --- Caching and redirects can be controlled in the options array, see module --- documentation for more information. +-- Caching and redirects can be controlled in the options array, +-- see module documentation for more information. -- -- @param host The host to connect to. -- @param port The port to connect to. -- @param path The path to retrieve. --- @param options [optional] A table that lets the caller control socket timeouts, HTTP headers, and other parameters. For full documentation, see the module documentation (above). +-- @param options [optional] A table that lets the caller control socket +-- timeouts, HTTP headers, and other parameters. For full +-- documentation, see the module documentation (above). -- @return A response table, see module documentation for description. -- @see http.generic_request function get(host, port, path, options) @@ -1520,13 +1524,15 @@ function get_url( u, options ) return get( parsed.host, port, path, options ) end ----Fetches a resource with a HEAD request. Like get, this is a simple --- wrapper around generic_request with response caching. This function --- also has support for HTTP redirects. Redirects are followed only if they pass --- all the validation rules of the redirect_ok function. This function may be --- overridden by supplying a custom function in the redirect_ok field --- of the options array. The default function redirects the request if the --- destination is: +---Fetches a resource with a HEAD request. +-- +-- Like get, this is a simple wrapper around +-- generic_request with response caching. This function also has +-- support for HTTP redirects. Redirects are followed only if they pass all the +-- validation rules of the redirect_ok function. This function may be +-- overridden by supplying a custom function in the redirect_ok +-- field of the options array. The default function redirects the request if +-- the destination is: -- * Within the same host or domain -- * Has the same port number -- * Stays within the current scheme @@ -1538,7 +1544,9 @@ end -- @param host The host to connect to. -- @param port The port to connect to. -- @param path The path to retrieve. --- @param options [optional] A table that lets the caller control socket timeouts, HTTP headers, and other parameters. For full documentation, see the module documentation (above). +-- @param options [optional] A table that lets the caller control socket +-- timeouts, HTTP headers, and other parameters. For full +-- documentation, see the module documentation (above). -- @return A response table, see module documentation for description. -- @see http.generic_request function head(host, port, path, options) @@ -1565,16 +1573,21 @@ function head(host, port, path, options) return response end ----Fetches a resource with a POST request. Like get, this is a simple --- wrapper around generic_request except that postdata is handled --- properly. +---Fetches a resource with a POST request. +-- +-- Like get, this is a simple wrapper around +-- generic_request except that postdata is handled properly. -- -- @param host The host to connect to. -- @param port The port to connect to. -- @param path The path to retrieve. --- @param options [optional] A table that lets the caller control socket timeouts, HTTP headers, and other parameters. For full documentation, see the module documentation (above). +-- @param options [optional] A table that lets the caller control socket +-- timeouts, HTTP headers, and other parameters. For full +-- documentation, see the module documentation (above). -- @param ignored Ignored for backwards compatibility. --- @param postdata A string or a table of data to be posted. If a table, the keys and values must be strings, and they will be encoded into an application/x-www-form-encoded form submission. +-- @param postdata A string or a table of data to be posted. If a table, the +-- keys and values must be strings, and they will be encoded +-- into an application/x-www-form-encoded form submission. -- @return A response table, see module documentation for description. -- @see http.generic_request function post( host, port, path, options, ignored, postdata ) @@ -1607,22 +1620,30 @@ function pipeline(host, port, allReqs) end ----Adds a pending request to the HTTP pipeline. The HTTP pipeline is a set of requests that will --- all be sent at the same time, or as close as the server allows. This allows more efficient --- code, since requests are automatically buffered and sent simultaneously. +---Adds a pending request to the HTTP pipeline. -- --- The all_requests argument contains the current list of queued requests (if this --- is the first time calling pipeline_add, it should be nil). After --- adding the request to end of the queue, the queue is returned and can be passed to the next +-- The HTTP pipeline is a set of requests that will all be sent at the same +-- time, or as close as the server allows. This allows more efficient code, +-- since requests are automatically buffered and sent simultaneously. +-- +-- The all_requests argument contains the current list of queued +-- requests (if this is the first time calling pipeline_add, it +-- should be nil). After adding the request to end of the queue, +-- the queue is returned and can be passed to the next -- pipeline_add call. -- --- When all requests have been queued, call pipeline_go with the all_requests table --- that has been built. +-- When all requests have been queued, call pipeline_go with the +-- all_requests table that has been built. -- -- @param path The path to retrieve. --- @param options [optional] A table that lets the caller control socket timeouts, HTTP headers, and other parameters. For full documentation, see the module documentation (above). --- @param all_requests [optional] The current pipeline queue (returned from a previous add_pipeline call), or nil if it's the first call. --- @param method [optional] The HTTP method ('GET', 'HEAD', 'POST', etc). Default: 'GET'. +-- @param options [optional] A table that lets the caller control socket +-- timeouts, HTTP headers, and other parameters. For full +-- documentation, see the module documentation (above). +-- @param all_requests [optional] The current pipeline queue (returned from a +-- previous add_pipeline call), or nil if it's +-- the first call. +-- @param method [optional] The HTTP method ('GET', 'HEAD', 'POST', etc). +-- Default: 'GET'. -- @return Table with the pipeline get requests (plus this new one) -- @see http.pipeline_go function pipeline_add(path, options, all_requests, method) @@ -1646,13 +1667,16 @@ function pipeline_add(path, options, all_requests, method) end ---Performs all queued requests in the all_requests variable (created by the --- pipeline_add function). Returns an array of responses, each of --- which is a table as defined in the module documentation above. +-- pipeline_add function). +-- +-- Returns an array of responses, each of which is a table as defined in the +-- module documentation above. -- -- @param host The host to connect to. -- @param port The port to connect to. -- @param all_requests A table with all the previously built pipeline requests --- @return A list of responses, in the same order as the requests were queued. Each response is a table as described in the module documentation. +-- @return A list of responses, in the same order as the requests were queued. +-- Each response is a table as described in the module documentation. function pipeline_go(host, port, all_requests) stdnse.print_debug("Total number of pipelined requests: " .. #all_requests) local responses @@ -1849,6 +1873,7 @@ end --- -- Finds forms in html code +-- -- returns table of found forms, in plaintext. -- @param body A response.body in which to search for forms -- @return A list of forms. @@ -1947,8 +1972,9 @@ local MONTH_MAP = { Jul = 7, Aug = 8, Sep = 9, Oct = 10, Nov = 11, Dec = 12 } ---- Parses an HTTP date string, in any of the following formats from section --- 3.3.1 of RFC 2616: +--- Parses an HTTP date string +-- +-- Supports any of the following formats from section 3.3.1 of RFC 2616: -- * Sun, 06 Nov 1994 08:49:37 GMT (RFC 822, updated by RFC 1123) -- * Sunday, 06-Nov-94 08:49:37 GMT (RFC 850, obsoleted by RFC 1036) -- * Sun Nov 6 08:49:37 1994 (ANSI C's asctime() format) @@ -2055,9 +2081,10 @@ local function read_auth_challenge(s, pos) end ---Parses the WWW-Authenticate header as described in RFC 2616, section 14.47 --- and RFC 2617, section 1.2. The return value is an array of challenges. Each --- challenge is a table with the keys scheme and --- params. +-- and RFC 2617, section 1.2. +-- +-- The return value is an array of challenges. Each challenge is a table with +-- the keys scheme and params. -- @param s The header value text. -- @return An array of challenges, or nil on error. function parse_www_authenticate(s) @@ -2105,9 +2132,11 @@ function get_status_string(data) end end ----Determine whether or not the server supports HEAD by requesting / and --- verifying that it returns 200, and doesn't return data. We implement the --- check like this because can't always rely on OPTIONS to tell the truth. +---Determine whether or not the server supports HEAD. +-- +-- Tests by requesting / and verifying that it returns 200, and doesn't return +-- data. We implement the check like this because can't always rely on OPTIONS +-- to tell the truth. -- -- Note: If identify_404 returns a 200 status, HEAD requests -- should be disabled. Sometimes, servers use a 200 status code with a message @@ -2119,12 +2148,12 @@ end -- @param host The host object. -- @param port The port to use. -- @param result_404 [optional] The result when an unknown page is requested. --- This is returned by identify_404. If the 404 page returns a --- 200 code, then we disable HEAD requests. +-- This is returned by identify_404. If the 404 +-- page returns a 200 code, then we disable HEAD requests. -- @param path The path to request; by default, / is used. -- @return A boolean value: true if HEAD is usable, false otherwise. -- @return If HEAD is usable, the result of the HEAD request is returned (so --- potentially, a script can avoid an extra call to HEAD +-- potentially, a script can avoid an extra call to HEAD) function can_use_head(host, port, result_404, path) -- If the 404 result is 200, don't use HEAD. if(result_404 == 200) then @@ -2163,7 +2192,9 @@ function can_use_head(host, port, result_404, path) return false end ---- Try and remove anything that might change within a 404. For example: +--- Try to remove anything that might change within a 404. +-- +-- For example: -- * A file path (includes URI) -- * A time -- * A date @@ -2220,18 +2251,24 @@ function clean_404(body) end ---Try requesting a non-existent file to determine how the server responds to --- unknown pages ("404 pages"), which a) tells us what to expect when a --- non-existent page is requested, and b) tells us if the server will be --- impossible to scan. If the server responds with a 404 status code, as it is --- supposed to, then this function simply returns 404. If it contains one of a --- series of common status codes, including unauthorized, moved, and others, it --- is returned like a 404. +-- unknown pages ("404 pages") +-- +-- This tells us +-- * what to expect when a non-existent page is requested, and +-- * if the server will be impossible to scan. +-- +-- If the server responds with a 404 status code, as it is supposed to, then +-- this function simply returns 404. If it contains one of a series of common +-- status codes, including unauthorized, moved, and others, it is returned like +-- a 404. -- -- I (Ron Bowes) have observed one host that responds differently for three -- scenarios: -- * A non-existent page, all lowercase (a login page) --- * A non-existent page, with uppercase (a weird error page that says, "Filesystem is corrupt.") --- * A page in a non-existent directory (a login page with different font colours) +-- * A non-existent page, with uppercase (a weird error page that says, +-- "Filesystem is corrupt.") +-- * A page in a non-existent directory (a login page with different font +-- colours) -- -- As a result, I've devised three different 404 tests, one to check each of -- these conditions. They all have to match, the tests can proceed; if any of @@ -2240,8 +2277,11 @@ end -- @param host The host object. -- @param port The port to which we are establishing the connection. -- @return status Did we succeed? --- @return result If status is false, result is an error message. Otherwise, it's the code to expect (typically, but not necessarily, '404'). --- @return body Body is a hash of the cleaned-up body that can be used when detecting a 404 page that doesn't return a 404 error code. +-- @return result If status is false, result is an error message. Otherwise, +-- it's the code to expect (typically, but not necessarily, +-- '404'). +-- @return body Body is a hash of the cleaned-up body that can be used when +-- detecting a 404 page that doesn't return a 404 error code. function identify_404(host, port) local data local bad_responses = { 301, 302, 400, 401, 403, 499, 501, 503 } @@ -2332,16 +2372,24 @@ function identify_404(host, port) return true, data.status end ---- Determine whether or not the page that was returned is a 404 page. This is ---actually a pretty simple function, but it's best to keep this logic close to ---identify_404, since they will generally be used together. +--- Determine whether or not the page that was returned is a 404 page. +-- +-- This is actually a pretty simple function, but it's best to keep this logic +-- close to identify_404, since they will generally be used +-- together. -- -- @param data The data returned by the HTTP request --- @param result_404 The status code to expect for non-existent pages. This is returned by identify_404. --- @param known_404 The 404 page itself, if result_404 is 200. If result_404 is something else, this parameter is ignored and can be set to nil. This is returned by identify_404. +-- @param result_404 The status code to expect for non-existent pages. This is +-- returned by identify_404. +-- @param known_404 The 404 page itself, if result_404 is 200. If +-- result_404 is something else, this parameter +-- is ignored and can be set to nil. This is +-- returned by identify_404. -- @param page The page being requested (used in error messages). --- @param displayall [optional] If set to true, don't exclude non-404 errors (such as 500). --- @return A boolean value: true if the page appears to exist, and false if it does not. +-- @param displayall [optional] If set to true, don't exclude non-404 errors +-- (such as 500). +-- @return A boolean value: true if the page appears to exist, and false if it +-- does not. function page_exists(data, result_404, known_404, page, displayall) if(data and data.status) then -- Handle the most complicated case first: the "200 Ok" response @@ -2388,8 +2436,10 @@ function page_exists(data, result_404, known_404, page, displayall) end end ----Check if the response variable, which could be a return from a http.get, http.post, http.pipeline, --- etc, contains the given text. The text can be: +---Check if the response variable contains the given text. +-- +-- Response variable could be a return from a http.get, http.post, +-- http.pipeline, etc. The text can be: -- * Part of a header ('content-type', 'text/html', '200 OK', etc) -- * An entire header ('Content-type: text/html', 'Content-length: 123', etc) -- * Part of the body @@ -2397,8 +2447,12 @@ end -- The search text is treated as a Lua pattern. -- --@param response The full response table from a HTTP request. ---@param pattern The pattern we're searching for. Don't forget to escape '-', for example, 'Content%-type'. The pattern can also contain captures, like 'abc(.*)def', which will be returned if successful. ---@param case_sensitive [optional] Set to true for case-sensitive searches. Default: not case sensitive. +--@param pattern The pattern we're searching for. Don't forget to escape '-', +-- for example, 'Content%-type'. The pattern can also contain +-- captures, like 'abc(.*)def', which will be returned if +-- successful. +--@param case_sensitive [optional] Set to true for case-sensitive +-- searches. Default: not case sensitive. --@return result True if the string matched, false otherwise --@return matches An array of captures from the match, if any function response_contains(response, pattern, case_sensitive) @@ -2442,13 +2496,22 @@ function response_contains(response, pattern, case_sensitive) return false end ----Take a URI or URL in any form and convert it to its component parts. The URL can optionally --- have a protocol definition ('http://'), a server ('scanme.insecure.org'), a port (':80'), a --- URI ('/test/file.php'), and a query string ('?username=ron&password=turtle'). At the minimum, --- a path or protocol and url are required. +---Take a URI or URL in any form and convert it to its component parts. +-- +-- The URL can optionally have a protocol definition ('http://'), a server +-- ('scanme.insecure.org'), a port (':80'), a URI ('/test/file.php'), and a +-- query string ('?username=ron&password=turtle'). At the minimum, a path or +-- protocol and url are required. -- --@param url The incoming URL to parse ---@return result A table containing the result, which can have the following fields: protocol, hostname, port, uri, querystring. All fields are strings except querystring, which is a table containing name=value pairs. +--@return A table containing the result, which can have the following fields: +-- * protocol +-- * hostname +-- * port +-- * uri +-- * querystring +-- All fields are strings except querystring, which is a table +-- containing name=value pairs. function parse_url(url) local result = {} @@ -2526,14 +2589,21 @@ function parse_url(url) return result end ----This function should be called whenever a valid path (a path that doesn't contain a known --- 404 page) is discovered. It will add the path to the registry in several ways, allowing --- other scripts to take advantage of it in interesting ways. +---This function should be called whenever a valid path (a path that doesn't +-- contain a known 404 page) is discovered. -- ---@param host The host the path was discovered on (not necessarily the host being scanned). ---@param port The port the path was discovered on (not necessarily the port being scanned). ---@param path The path discovered. Calling this more than once with the same path is okay; it'll update the data as much as possible instead of adding a duplicate entry ---@param status [optional] The status code (200, 404, 500, etc). This can be left off if it isn't known. +-- It will add the path to the registry in several ways, allowing other scripts +-- to take advantage of it in interesting ways. +-- +--@param host The host the path was discovered on (not necessarily the host +-- being scanned). +--@param port The port the path was discovered on (not necessarily the port +-- being scanned). +--@param path The path discovered. Calling this more than once with the same +-- path is okay; it'll update the data as much as possible instead +-- of adding a duplicate entry +--@param status [optional] The status code (200, 404, 500, etc). This can be +-- left off if it isn't known. --@param links_to [optional] A table of paths that this page links to. --@param linked_from [optional] A table of paths that link to this page. --@param contenttype [optional] The content-type value for the path, if it's known. diff --git a/nselib/informix.lua b/nselib/informix.lua index ee23538f6..ac9aad6e8 100644 --- a/nselib/informix.lua +++ b/nselib/informix.lua @@ -1003,6 +1003,7 @@ Packet.Connect = { getErrMsg = function( self ) return self.errmsg end, --- Reads and decodes the response to the connect packet from the server. + -- -- The function will return true even if the response contains an Informix -- error. In order to verify if the connection was successful, check for OS -- or service errors using the getSvcError and getOsError methods. @@ -1203,6 +1204,7 @@ Helper = { end, --- Attempts to login to the Informix database server + -- -- The optional parameters parameter takes any informix specific parameters -- used to connect to the database. In case it's omitted a set of default -- parameters are set. Parameters should be past as key, value pairs inside diff --git a/nselib/ipOps.lua b/nselib/ipOps.lua index 4220e2370..55c1c4005 100644 --- a/nselib/ipOps.lua +++ b/nselib/ipOps.lua @@ -214,15 +214,18 @@ end --- --- Compares two IP addresses. When comparing addresses from different families, +-- Compares two IP addresses. +-- +-- When comparing addresses from different families, -- IPv4 addresses will sort before IPv6 addresses. --- @param left String representing an IPv4 or IPv6 address. Shortened --- notation is permitted. --- @param op A comparison operator which may be one of the following --- strings: "eq", "ge", "le", --- "gt" or "lt" (respectively ==, >=, <=, >, <). --- @param right String representing an IPv4 or IPv6 address. Shortened --- notation is permitted. +-- @param left String representing an IPv4 or IPv6 address. Shortened +-- notation is permitted. +-- @param op A comparison operator which may be one of the following strings: +-- "eq", "ge", "le", +-- "gt" or "lt" (respectively ==, >=, <=, +-- >, <). +-- @param right String representing an IPv4 or IPv6 address. Shortened +-- notation is permitted. -- @usage -- if ipOps.compare_ip( "2001::DEAD:0:0:0", "eq", "2001:0:0:0:DEAD::" ) then -- ... @@ -477,14 +480,14 @@ end --- -- Calculates the last IP address of a range of addresses given an IP address in -- the range and prefix length for that range. --- @param ip String representing an IPv4 or IPv6 address. Shortened --- notation is permitted. --- @param prefix Number or a string representing a decimal number corresponding --- to a prefix length. +-- @param ip String representing an IPv4 or IPv6 address. Shortened notation +-- is permitted. +-- @param prefix Number or a string representing a decimal number corresponding +-- to a prefix length. -- @usage -- last = ipOps.get_last_ip( "192.0.0.0", 26 ) --- @return String representing the last IP address of the range denoted --- by the supplied parameters (or nil in case of an error). +-- @return String representing the last IP address of the range denoted by the +-- supplied parameters (or nil in case of an error). -- @return String error message in case of an error. get_last_ip = function( ip, prefix ) @@ -543,13 +546,13 @@ end --- -- Converts an IP address into a string representing the address as binary -- digits. --- @param ip String representing an IPv4 or IPv6 address. Shortened notation --- is permitted. +-- @param ip String representing an IPv4 or IPv6 address. Shortened notation +-- is permitted. -- @usage -- bit_string = ipOps.ip_to_bin( "2001::" ) --- @return String representing the supplied IP address as 32 or 128 binary --- digits (or nil in case of an error). --- @return String error message in case of an error. +-- @return String representing the supplied IP address as 32 or 128 binary +-- digits (or nil in case of an error). +-- @return String error message in case of an error. ip_to_bin = function( ip ) local err diff --git a/nselib/json.lua b/nselib/json.lua index fa6e18b37..b46002ee7 100644 --- a/nselib/json.lua +++ b/nselib/json.lua @@ -81,8 +81,9 @@ local function escape(str) end --- Makes a table be treated as a JSON Array when generating JSON --- A table treated as an Array has all non-number indices ignored. --- () param t a table to be treated as an array +-- +-- A table treated as an Array has all non-number indices ignored. +-- @param t a table to be treated as an array function make_array(t) local mt = getmetatable(t) or {} mt["json"] = "array" @@ -90,8 +91,9 @@ function make_array(t) end --- Makes a table be treated as a JSON Object when generating JSON --- A table treated as an Object has all non-number indices ignored. --- () param t a table to be treated as an object +-- +-- A table treated as an Object has all non-number indices ignored. +-- @param t a table to be treated as an object function make_object(t) local mt = getmetatable(t) or {} mt["json"] = "object" @@ -99,8 +101,8 @@ function make_object(t) end --- Checks what JSON type a variable will be treated as when generating JSON --- () param var a variable to inspect --- () return a string containing the JSON type. Valid values are "array", +-- @param var a variable to inspect +-- @return a string containing the JSON type. Valid values are "array", -- "object", "number", "string", "boolean", and "null" function typeof(var) local t = type(var) @@ -437,6 +439,7 @@ end return val end --- Parses json data into an object form +-- -- This is the method you probably want to use if you -- use this library from a script. --@param data a json string diff --git a/nselib/msrpc.lua b/nselib/msrpc.lua index 7c862f93f..e8660d519 100644 --- a/nselib/msrpc.lua +++ b/nselib/msrpc.lua @@ -179,27 +179,34 @@ local UUID2EXE = { } ---- This is a wrapper around the SMB class, designed to get SMB going quickly for MSRPC calls. This will --- connect to the SMB server, negotiate the protocol, open a session, connect to the IPC$ share, and --- open the named pipe given by 'path'. When this successfully returns, the 'smbstate' table can be immediately --- used for MSRPC (the bind function should be called right after). +--- This is a wrapper around the SMB class, designed to get SMB going quickly for MSRPC calls. -- --- Note that the smbstate table is the same one used in the SMB files (obviously), so it will contain --- the various results/information places in there by SMB functions. +-- This will connect to the SMB server, negotiate the protocol, open a session, +-- connect to the IPC$ share, and open the named pipe given by 'path'. When +-- this successfully returns, the 'smbstate' table can be immediately used for +-- MSRPC (the bind function should be called right after). +-- +-- Note that the smbstate table is the same one used in the SMB files +-- (obviously), so it will contain the various results/information places in +-- there by SMB functions. -- --@param host The host object. ---@param path The path to the named pipe; for example, msrpc.SAMR_PATH or msrpc.SRVSVC_PATH. ---@param disable_extended [optional] If set to 'true', disables extended security negotiations. +--@param path The path to the named pipe; for example, msrpc.SAMR_PATH or +-- msrpc.SRVSVC_PATH. +--@param disable_extended [optional] If set to 'true', disables extended +-- security negotiations. --@param overrides [optional] Overrides variables in all the SMB functions. ---@return (status, smbstate) if status is false, smbstate is an error message. Otherwise, smbstate is --- required for all further calls. +--@return status true or false +--@return smbstate if status is true, or an error message. function start_smb(host, path, disable_extended, overrides) overrides = overrides or {} return smb.start_ex(host, true, true, "IPC$", path, disable_extended, overrides) end ---- A wrapper around the smb.stop function. I only created it to add symmetry, so client code --- doesn't have to call both msrpc and smb functions. +--- A wrapper around the smb.stop function. +-- +-- I only created it to add symmetry, so client code doesn't have to call both +-- msrpc and smb functions. -- --@param state The SMB state table. function stop_smb(state) @@ -344,23 +351,33 @@ function bind(smbstate, interface_uuid, interface_version, transfer_syntax) return true, result end ---- Call a MSRPC function on the remote sever, with the given opnum and arguments. I opted to make this a local function --- for design reasons -- scripts shouldn't be directly calling a function, if a function I haven't written is needed, it --- ought to be added to this file. +--- Call a MSRPC function on the remote server, with the given opnum and arguments. -- --- Anyways, this function takes the opnum and marshalled arguments, and passes it down to the SMB layer. The SMB layer sends --- out a SMB_COM_TRANSACTION packet, and parses the result. Once the SMB stuff has been stripped off the result, it's --- passed down here, cleaned up some more, and returned to the caller. +-- I opted to make this a local function for design reasons -- scripts +-- shouldn't be directly calling a function, if a function I haven't written is +-- needed, it ought to be added to this file. -- --- There's a reason that SMB is sometimes considered to be between layer 4 and 7 on the OSI model. :) +-- Anyways, this function takes the opnum and marshalled arguments, and passes +-- it down to the SMB layer. The SMB layer sends out a +-- SMB_COM_TRANSACTION packet, and parses the result. Once the SMB +-- stuff has been stripped off the result, it's passed down here, cleaned up +-- some more, and returned to the caller. -- ---@param smbstate The SMB state table (after bind has been called). ---@param opnum The operating number (ie, the function). Find this in the MSRPC documentation or with a packet logger. ---@param arguments The marshalled arguments to pass to the function. Currently, marshalling is all done manually. ---@return (status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most --- useful one being 'arguments', which are the values returned by the server. If the packet is fragmented, the fragments --- will be reassembled and 'arguments' will represent all the arguments; however, the rest of the result table will represent --- the most recent fragment. +-- There's a reason that SMB is sometimes considered to be between layer 4 and +-- 7 on the OSI model. :) +-- +--@param smbstate The SMB state table (after bind has been called). +--@param opnum The operating number (ie, the function). Find this in the +-- MSRPC documentation or with a packet logger. +--@param arguments The marshalled arguments to pass to the function. Currently, +-- marshalling is all done manually. +--@return status true or false +--@return If status is false, result is an error message. Otherwise, result is +-- a table of values, the most useful one being 'arguments', which are +-- the values returned by the server. If the packet is fragmented, the +-- fragments will be reassembled and 'arguments' will represent all the +-- arguments; however, the rest of the result table will represent the +-- most recent fragment. function call_function(smbstate, opnum, arguments) local i local status, result @@ -549,9 +566,11 @@ function rap_netserverenum2(smbstate, domain, server_type, detail_level) return true, entries end ----A proxy to a msrpctypes function that converts a ShareType to an english string. --- I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes --- functions. +---A proxy to a msrpctypes function that converts a ShareType to +-- an English string. +-- +-- I implemented this as a proxy so scripts don't have to make direct calls to +-- msrpctypes functions. -- --@param val The value to convert. --@return A string that can be displayed to the user. @@ -559,13 +578,17 @@ function srvsvc_ShareType_tostr(val) return msrpctypes.srvsvc_ShareType_tostr(val) end ----Call the MSRPC function netshareenumall on the remote system. This function basically returns a list of all the shares --- on the system. +---Call the MSRPC function netshareenumall on the remote system. +-- +-- This function basically returns a list of all the shares on the system. -- --@param smbstate The SMB state table ---@param server The IP or Hostname of the server (seems to be ignored but it's a good idea to have it) ---@return (status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most --- useful one being 'shares', which is a list of the system's shares. +--@param server The IP or Hostname of the server (seems to be ignored but it's +-- a good idea to have it) +--@return status true or false +--@return If status is false, result is an error message. Otherwise, result is +-- a table of values, the most useful one being 'shares', which is a +-- list of the system's shares. function srvsvc_netshareenumall(smbstate, server) local i, j local status, result @@ -1281,9 +1304,10 @@ function epmapper_lookup(smbstate,handle) return status,lookup_response end ----A proxy to a msrpctypes function that converts a PasswordProperties to an english string. --- I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes --- functions. +---A proxy to a msrpctypes function that converts a PasswordProperties to an English string. +-- +-- I implemented this as a proxy so scripts don't have to make direct calls to +-- msrpctypes functions. -- --@param val The value to convert. --@return A string that can be displayed to the user. @@ -1291,9 +1315,11 @@ function samr_PasswordProperties_tostr(val) return msrpctypes.samr_PasswordProperties_tostr(val) end ----A proxy to a msrpctypes function that converts a AcctFlags to an english string. --- I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes --- functions. +---A proxy to a msrpctypes function that converts a AcctFlags to +-- an English string. +-- +-- I implemented this as a proxy so scripts don't have to make direct calls to +-- msrpctypes functions. -- --@param val The value to convert. --@return A string that can be displayed to the user. @@ -1301,13 +1327,17 @@ function samr_AcctFlags_tostr(val) return msrpctypes.samr_AcctFlags_tostr(val) end ----Call the connect4 function, to obtain a "connect handle". This must be done before calling many --- of the SAMR functions. +---Call the connect4 function, to obtain a "connect handle". -- ---@param smbstate The SMB state table ---@param server The IP or Hostname of the server (seems to be ignored but it's a good idea to have it) ---@return (status, result) If status is false, result is an error message. Otherwise, result is a table of values, the most --- useful one being 'connect_handle', which is required to call other functions. +-- This must be done before calling many of the SAMR functions. +-- +--@param smbstate The SMB state table +--@param server The IP or Hostname of the server (seems to be ignored but it's +-- a good idea to have it) +--@return status true or false +--@return If status is false, result is an error message. Otherwise, result is +-- a table of values, the most useful one being 'connect_handle', which +-- is required to call other functions. function samr_connect4(smbstate, server) local i, j local status, result @@ -2359,9 +2389,11 @@ function lsa_close(smbstate, handle) return true, result end ----A proxy to a msrpctypes function that converts a SidType to an english string. --- I implemented this as a proxy so scripts don't have to make direct calls to msrpctypes --- functions. +---A proxy to a msrpctypes function that converts a SidType to an +-- English string. +-- +-- I implemented this as a proxy so scripts don't have to make direct calls to +-- msrpctypes functions. -- --@param val The value to convert. --@return A string that can be displayed to the user. @@ -3456,15 +3488,19 @@ function svcctl_queryservicestatus(smbstate, handle, control) return true, result end ----Calls the function JobAdd, which schedules a process to be run on the remote --- machine. This requires administrator privileges to run, and the command itself runs as --- SYSTEM. +---Calls the function JobAdd, which schedules a process to be run +-- on the remote machine. +-- +-- This requires administrator privileges to run, and the command itself runs +-- as SYSTEM. --@param smbstate The SMB state table. ---@param server The IP or Hostname of the server (seems to be ignored but it's a good idea to have it) ---@param command The command to run on the remote machine. The appropriate file(s) already --- have to be there, and this should be a full path. ---@param time (optional) The time at which to run the command. Default: 5 seconds from --- when the user logged in. +--@param server The IP or Hostname of the server (seems to be ignored but it's +-- a good idea to have it) +--@param command The command to run on the remote machine. The appropriate +-- file(s) already have to be there, and this should be a full +-- path. +--@param time [optional] The time at which to run the command. Default: 5 +-- seconds from when the user logged in. function atsvc_jobadd(smbstate, server, command, time) local i, j local status, result @@ -4290,25 +4326,29 @@ function get_domains(host) return true, response end ----Create a "service" on a remote machine. This service is linked to an executable that is already --- on the system. The name of the service can be whatever you want it to be. The service is created --- in the "stopped" state with "manual" startup, and it ignores errors. The 'servicename' is what --- people will see on the system while the service is running, and what'll stay there is something --- happens that the service can't be deleted properly. +---Create a "service" on a remote machine. -- --- Note that this (and the other "service" functions) are highly invasive. They make configuration --- changes to the machine that can potentially affect stability. +-- This service is linked to an executable that is already on the system. The +-- name of the service can be whatever you want it to be. The service is +-- created in the "stopped" state with "manual" startup, and it ignores errors. +-- The 'servicename' is what people will see on the system while the service is +-- running, and what'll stay there is something happens that the service can't +-- be deleted properly. -- --- The reason that this and the other "service" functions don't require a smbstate --- object is that I wanted them to be independent. If a service fails to start, I don't want it --- to affect the program's ability to stop and delete the service. Every service function is --- independent. +-- Note that this (and the other "service" functions) are highly invasive. They +-- make configuration changes to the machine that can potentially affect +-- stability. +-- +-- The reason that this and the other "service" functions don't require a +-- smbstate object is that I wanted them to be independent. If a +-- service fails to start, I don't want it to affect the program's ability to +-- stop and delete the service. Every service function is independent. -- --@param host The host object. --@param servicename The name of the service to create. --@param path The path and filename on the remote system. ---@return (status, err) If status is false, err is an error message; --- otherwise, err is undefined. +--@return status true or false +--@return error message if status is false function service_create(host, servicename, path) local status, smbstate, bind_result, open_result, create_result, close_result @@ -4595,12 +4635,15 @@ function service_delete(host, servicename) return true end ----Retrieves statistical information about the given server. This function requires administrator privileges --- to run, and is present on all Windows versions, so it's a useful way to check whether or not an account --- is administrative. ---@param host The host object ---@return (status, data) If status is false, data is an error message; otherwise, data is a table of information --- about the server. +---Retrieves statistical information about the given server. +-- +-- This function requires administrator privileges to run, and is present on +-- all Windows versions, so it's a useful way to check whether or not an +-- account is administrative. +--@param host The host object +--@return status true or false +--@return If status is false, data is an error message; otherwise, data is a +-- table of information about the server. function get_server_stats(host) local stats local status diff --git a/nselib/msrpcperformance.lua b/nselib/msrpcperformance.lua index 31409ca31..d52c9a043 100644 --- a/nselib/msrpcperformance.lua +++ b/nselib/msrpcperformance.lua @@ -421,13 +421,18 @@ local function parse_perf_counter_block(data, pos) return true, pos, result end ----Retrieve the parsed performance data from the given host for the requested object values. To get a list of possible --- object values, leave 'objects' blank and look at result['title_database'] -- it'll contain a list of --- indexes that can be looked up. These indexes are passed as a string or as a series of space-separated strings (eg, --- "230" for "Process" and "238" for "Process" and "Processor"). +---Retrieve the parsed performance data from the given host for the requested +-- object values. +-- +-- To get a list of possible object values, leave 'objects' blank and look at +-- result['title_database'] -- it'll contain a list of indexes +-- that can be looked up. These indexes are passed as a string or as a series +-- of space-separated strings (eg, "230" for "Process" and "238" for "Process" +-- and "Processor"). -- --@param host The host object ---@param objects [optional] The space-separated list of object numbers to retrieve. Default: only retrieve the database. +--@param objects [optional] The space-separated list of object numbers to +-- retrieve. Default: only retrieve the database. function get_performance_data(host, objects) -- Create the SMB session diff --git a/nselib/msrpctypes.lua b/nselib/msrpctypes.lua index 910ccc147..20aa9d42e 100644 --- a/nselib/msrpctypes.lua +++ b/nselib/msrpctypes.lua @@ -117,12 +117,16 @@ local HEAD = 'HEAD' local BODY = 'BODY' local ALL = 'ALL' ---- Convert a string to fake unicode (ascii with null characters between them), optionally add a null terminator, --- and optionally align it to 4-byte boundaries. This is frequently used in MSRPC calls, so I put it here, but --- it might be a good idea to move this function (and the converse one below) into a separate library. +--- Convert a string to Unicode (UTF-16 LE), optionally add a null terminator, +-- and align it to 4-byte boundaries. +-- +-- This is frequently used in MSRPC calls, so I put it here, but it might be a +-- good idea to move this function (and the converse one below) into a separate +-- library. -- --@param string The string to convert. ---@param do_null [optional] Add a null-terminator to the unicode string. Default false. +--@param do_null [optional] Add a null-terminator to the unicode string. +-- Default false. --@return The unicode version of the string. function string_to_unicode(string, do_null) local i @@ -199,19 +203,23 @@ end -- (dependencies: n/a) ------------------------------------- ----Marshalls a pointer to another datatype. This function will optionally separate the --- REFERENT_ID of the pointer (which goes at location = HEAD) from the data part of the --- pointer (which goes at location = BODY). If the entire pointer is needed, then location --- should be set to ALL. +---Marshalls a pointer to another datatype. -- --- When marshalling the body, the function func is called, which is passed as --- a parameter, with the arguments args. This function has to return a marshalled --- parameter, but other than that it can be any marshalling function. The 'value' parameter --- simply determined whether or not it's a null pointer, and will probably be a repeat of --- one of the arguments. +-- This function will optionally separate the REFERENT_ID of the pointer (which +-- goes at location = HEAD) from the data part of the pointer (which goes at +-- location = BODY). If the entire pointer is needed, then location should be +-- set to ALL. -- --- Note that the function func doesn't have to conform to any special prototype, --- as long as the args array matches what the function wants. +-- When marshalling the body, the function func is called, which +-- is passed as a parameter, with the arguments args. This +-- function has to return a marshalled parameter, but other than that it can be +-- any marshalling function. The 'value' parameter simply determined whether or +-- not it's a null pointer, and will probably be a repeat of one of the +-- arguments. +-- +-- Note that the function func doesn't have to conform to any +-- special prototype, as long as the args array matches what the +-- function wants. -- -- This can be used to marshall an int16 value of 0x1234 with padding like this: -- @@ -224,15 +232,16 @@ end -- marshall_ptr(ALL, marshall_unicode, {str, true}, str) -- -- ---@param location The part of the pointer wanted, either HEAD (for the referent_id), BODY --- (for the pointer data), or ALL (for both together). Generally, unless the --- referent_id is split from the data (for example, in an array), you will want --- ALL. ---@param func The function to call when encoding the body. Should convert the arguments passed --- in the args parameter to a string. ---@param args An array of arguments that will be directly passed to the function func ---@param value The value that's actually being encoded. This is simply used to determine whether or --- not the pointer is null. +--@param location The part of the pointer wanted, either HEAD (for the +-- referent_id), BODY (for the pointer data), or ALL (for both +-- together). Generally, unless the referent_id is split from +-- the data (for example, in an array), you will want ALL. +--@param func The function to call when encoding the body. Should convert the +-- arguments passed in the args parameter to a string. +--@param args An array of arguments that will be directly passed to the +-- function func +--@param value The value that's actually being encoded. This is simply used to +-- determine whether or not the pointer is null. --@return A string representing the marshalled data. local function marshall_ptr(location, func, args, value) local result = "" @@ -262,34 +271,41 @@ local function marshall_ptr(location, func, args, value) return result end ----Unmarshalls a pointer by removing the referent_id in the HEAD section and the data in the --- BODY section (or both in the ALL section). Because the unmarshall function for the body is --- called if and only if the referent_id is non-zero, if the head and the body are split apart, --- the second call to this function has to know the context. This is the purpose for the result --- parameter, it is the result from the first time this is called. +---Unmarshalls a pointer by removing the referent_id in the HEAD section and +--the data in the BODY section (or both in the ALL section). +-- +-- Because the unmarshall function for the body is called if and only if the +-- referent_id is non-zero, if the head and the body are split apart, the +-- second call to this function has to know the context. This is the purpose +-- for the result parameter, it is the result from the first time +-- this is called. -- -- The function func has to conform to this format: -- -- func(data, pos, ) -- -- ---@param location The part of the pointer being processed, either HEAD (for the referent_id), BODY --- (for the pointer data), or ALL (for both together). Generally, unless the --- referent_id is split from the data (for example, in an array), you will want --- ALL. ---@param data The data being processed. ---@param pos The position within data ---@param func The function that's used to process the body data (only called if it isn't a null --- pointer). This function has to conform to a specific prototype, see above. ---@param args The arguments that'll be passed to the function func, after the data --- array and the position. ---@param result This is required when unmarshalling the BODY section, which always comes after --- unmarshalling the HEAD. It is the result returned for this parameter during the --- HEAD unmarshall. If the referent_id was '0', then this function doesn't unmarshall --- anything. ---@return (pos, result) The new position along with the result. For HEAD the result is either true --- for valid pointers or false for null pointers. For BODY or ALL, the result is --- nil for null pointers, or the data for valid pointers. +--@param location The part of the pointer being processed, either HEAD (for the +-- referent_id), BODY (for the pointer data), or ALL (for both +-- together). Generally, unless the referent_id is split from +-- the data (for example, in an array), you will want ALL. +--@param data The data being processed. +--@param pos The position within data +--@param func The function that's used to process the body data (only +-- called if it isn't a null pointer). This function has to conform +-- to a specific prototype, see above. +--@param args The arguments that'll be passed to the function +-- func, after the data array and the position. +--@param result This is required when unmarshalling the BODY section, which +-- always comes after unmarshalling the HEAD. It is the result +-- returned for this parameter during the HEAD unmarshall. If the +-- referent_id was '0', then this function doesn't unmarshall +-- anything. +--@return The new position +--@reutrn The result. For HEAD the result is either true for valid +-- pointers or false for null pointers. For BODY or ALL, +-- the result is nil for null pointers, or the data for +-- valid pointers. local function unmarshall_ptr(location, data, pos, func, args, result) stdnse.print_debug(4, "MSRPC: Entering unmarshall_ptr()") if(args == nil) then @@ -330,22 +346,26 @@ local function unmarshall_ptr(location, data, pos, func, args, result) end ---Similar to marshall_ptr, except that this marshalls a type that isn't a pointer. --- It also understands pointers, in the sense that it'll only return data in the HEAD section, since --- basetypes are printed in the HEAD and not the BODY. -- --- Using this isn't strictly necessary, but it cleans up functions for generating structs containing --- both pointers and basetypes (see marshall_srvsvc_NetShareInfo2). +-- It also understands pointers, in the sense that it'll only return data in +-- the HEAD section, since basetypes are printed in the HEAD and not the BODY. -- --- Like marshall_ptr, the function doesn't have to match any prototype, as long as the --- proper arguments are passed to it. +-- Using this isn't strictly necessary, but it cleans up functions for +-- generating structs containing both pointers and basetypes (see +-- marshall_srvsvc_NetShareInfo2). -- ---@param location The part of the pointer wanted, either HEAD (for the data itself), BODY --- (for nothing, since this isn't a pointer), or ALL (for the data). Generally, unless the --- referent_id is split from the data (for example, in an array), you will want +-- Like marshall_ptr, the function doesn't have to match any +-- prototype, as long as the proper arguments are passed to it. +-- +--@param location The part of the pointer wanted, either HEAD (for the data +-- itself), BODY (for nothing, since this isn't a pointer), or +-- ALL (for the data). Generally, unless the referent_id is +-- split from the data (for example, in an array), you will want -- ALL. ---@param func The function to call when encoding the body. Should convert the arguments passed --- in the args parameter to a string. ---@param args An array of arguments that will be directly passed to the function func +--@param func The function to call when encoding the body. Should convert the +-- arguments passed in the args parameter to a string. +--@param args An array of arguments that will be directly passed to the +-- function func --@return A string representing the marshalled data. local function marshall_basetype(location, func, args) local result @@ -362,23 +382,27 @@ local function marshall_basetype(location, func, args) return result end ----Marshalls an array. Recall (from the module comment) that the data in an array is split into the --- referent_ids and base types at the top and the data at the bottom. This function will call --- any number of location-aware functions twice (once for the top and once for the bottom). +---Marshalls an array. -- --- Each element in the array can technically have a different function. I don't know why I allowed --- that, and may refactor it out in the future. For now, I strongly recommend setting the function --- to the same for every element. +-- Recall (from the module comment) that the data in an array is split into the +-- referent_ids and base types at the top and the data at the bottom. This +-- function will call any number of location-aware functions twice (once for +-- the top and once for the bottom). +-- +-- Each element in the array can technically have a different function. I don't +-- know why I allowed that, and may refactor it out in the future. For now, I +-- strongly recommend setting the function to the same for every element. -- -- The function that's called has to have the prototype: -- -- func(location, ) -- --- where "location" is the standard HEAD/BODY/ALL location used throughout the functions. +-- where "location" is the standard HEAD/BODY/ALL location used throughout the +-- functions. -- ---@param array An array of tables. Each table contains 'func', a pointer to the marshalling --- function and 'args', the arguments to pass to the marshalling function after the --- 'location' variable. +--@param array An array of tables. Each table contains 'func', a pointer to the +-- marshalling function and 'args', the arguments to pass to the +-- marshalling function after the 'location' variable. --@return A string representing the marshalled data. function marshall_array(array) local i @@ -411,29 +435,34 @@ function marshall_array(array) return result end ----Unmarshalls an array. This function starts to get a little hairy, due to the number of --- parameters that need to be propagated, but it isn't too bad. Basically, this unmarshalls an --- array by calling the given function for each element. +---Unmarshalls an array. +-- +-- This function starts to get a little hairy, due to the number of parameters +-- that need to be propagated, but it isn't too bad. Basically, this +-- unmarshalls an array by calling the given function for each element. -- -- The function func has to conform to a very specific prototype: -- -- func(location, data, pos, result, ) -- --- Where location is the standard HEAD/BODY location, data and pos --- are the packet and position within it, result is the result from the HEAD section (if --- it's nil, it isn't used), and args are arbitrary arguments passed to it. +-- Where location is the standard HEAD/BODY location, +-- data and pos are the packet and position within it, +-- result is the result from the HEAD section (if it's nil, it +-- isn't used), and args are arbitrary arguments passed to it. -- --- I made the call to pass the same arguments to each function when it's called. This is, for example, --- whether or not to null-terminate a string, or whether or not to pad an int16. If different types are --- required, you're probably out of luck. +-- I made the call to pass the same arguments to each function when it's +-- called. This is, for example, whether or not to null-terminate a string, or +-- whether or not to pad an int16. If different types are required, you're +-- probably out of luck. -- --@param data The data being processed. --@param pos The position within data. --@param count The number of elements in the array. ---@param func The function to call to unmarshall each parameter. Has to match a specific prototype; --- see the function comment. +--@param func The function to call to unmarshall each parameter. Has to match a +-- specific prototype; see the function comment. --@param args Arbitrary arguments to pass to the function. ---@return (pos, result) The new position and the result of unmarshalling this value. +--@return The new position +--@return The result of unmarshalling this value. local function unmarshall_array(data, pos, count, func, args) local i local size @@ -467,23 +496,26 @@ local function unmarshall_array(data, pos, count, func, args) return pos, result end ----Call a function that matches the prototype for unmarshall_array. This allows the same --- struct to be used in unmarshall_array and in unmarshall_ptr. It is kind --- of a kludge, but it makes sense, and was the cleanest solution I could come up with to this problem --- (although I'm sure that there's a better one staring me in the face). +---Call a function that matches the prototype for unmarshall_array. -- --- The func parameter, obviously, has to match the same prototype as strings being passed to --- unmarshall_array, which is: +-- This allows the same struct to be used in unmarshall_array and +-- in unmarshall_ptr. It is kind of a kludge, but it makes sense, +-- and was the cleanest solution I could come up with to this problem (although +-- I'm sure that there's a better one staring me in the face). +-- +-- The func parameter, obviously, has to match the same prototype +-- as strings being passed to unmarshall_array, which is: -- -- func(location, data, pos, result, ) -- -- --@param data The data being processed. --@param pos The position within data. ---@param func The function to call to unmarshall each parameter. Has to match a specific prototype; --- see the function comment. +--@param func The function to call to unmarshall each parameter. Has to match a +-- specific prototype; see the function comment. --@param args Arbitrary arguments to pass to the function. ---@return (pos, result) The new position and the result of unmarshalling this value. +--@return The new position +--@return The result of unmarshalling this value. local function unmarshall_struct(data, pos, func, args) local result @@ -889,6 +921,7 @@ end --- Marshall a pointer to an int32, which has the following format: -- [in,out] uint32 *ptr +-- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, -- it uses a referent id followed by the integer. -- @@ -906,6 +939,7 @@ end --- Marshall a pointer to an int16, which has the following format: -- [in,out] uint16 *ptr +-- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, -- it uses a referent id followed by the integer. -- @@ -924,6 +958,7 @@ end --- Marshall a pointer to an int8, which has the following format: -- [in,out] uint8 *ptr +-- -- If the pointer is null, it simply marshalls the integer '0'. Otherwise, -- it uses a referent id followed by the integer. -- @@ -1110,10 +1145,12 @@ function unmarshall_int32_array_ptr(data, pos) return pos, array end ----Marshalls an NTTIME. This is sent as the number of 1/10 microseconds since 1601; however --- the internal representation is the number of seconds since 1970. Because doing conversions --- in code is annoying, the user will never have to understand anything besides seconds since --- 1970. +---Marshalls an NTTIME. +-- +-- This is sent as the number of 1/10 microseconds since 1601; however the +-- internal representation is the number of seconds since 1970. Because doing +-- conversions in code is annoying, the user will never have to understand +-- anything besides seconds since 1970. -- --@param time The time, in seconds since 1970. --@return A string representing the marshalled data. @@ -1213,9 +1250,12 @@ function unmarshall_SYSTEMTIME(data, pos) return pos, os.time(date) end ----Unmarshalls a hyper. I have no idea what a hyper is, just that it seems --- to be a 64-bit data type used for measuring time, and that the units happen to be negative --- microseconds. This function converts the value to seconds and returns it. +---Unmarshalls a hyper. +-- +-- I have no idea what a hyper is, just that it seems to be a +-- 64-bit data type used for measuring time, and that the units happen to be +-- negative microseconds. This function converts the value to seconds and +-- returns it. -- --@param data The data packet. --@param pos The position within the data. @@ -1231,13 +1271,16 @@ function unmarshall_hyper(data, pos) return pos, result end ----Marshall an entry in a table. Basically, converts the string to a number based on the entries in --- table before sending. Multiple values can be ORed together (like flags) by separating --- them with pipes ("|"). +---Marshall an entry in a table. -- ---@param val The value to look up. Can be multiple values with pipes between, eg, "A|B|C". ---@param table The table to use for lookups. The keys should be the names, and the values should be --- the numbers. +-- Basically, converts the string to a number based on the entries in +-- table before sending. Multiple values can be ORed together +-- (like flags) by separating them with pipes ("|"). +-- +--@param val The value to look up. Can be multiple values with pipes between, +-- e.g. "A|B|C". +--@param table The table to use for lookups. The keys should be the names, and +-- the values should be the numbers. --@return A string representing the marshalled data. local function marshall_Enum32(val, table) local result = 0 @@ -1313,13 +1356,16 @@ local function unmarshall_Enum16(data, pos, table, default, pad) return pos, default end ----Marshall an entry in a table. Basically, converts the string to a number based on the entries in --- table before sending. Multiple values can be ORed together (like flags) by separating --- them with pipes ("|"). +---Marshall an entry in a table. -- ---@param val The value to look up. Can be multiple values with pipes between, eg, "A|B|C". ---@param table The table to use for lookups. The keys should be the names, and the values should be --- the numbers. +-- Basically, converts the string to a number based on the entries in +-- table before sending. Multiple values can be ORed together +-- (like flags) by separating them with pipes ("|"). +-- +--@param val The value to look up. Can be multiple values with pipes between, +-- e.g. "A|B|C". +--@param table The table to use for lookups. The keys should be the names, and +-- the values should be the numbers. --@param pad [optional] If set, will ensure that we end up on an even multiple of 4. Default: true. --@return A string representing the marshalled data. local function marshall_Enum8(val, table, pad) diff --git a/nselib/mssql.lua b/nselib/mssql.lua index e4d9bbb26..79f518ffc 100644 --- a/nselib/mssql.lua +++ b/nselib/mssql.lua @@ -207,12 +207,13 @@ SqlServerInstanceInfo = return areEqual end, - --- Merges the data from one SqlServerInstanceInfo object into another. Each - -- field in the first object is populated with the data from that field in - -- second object if the first object's field is nil OR if overwrite - -- is set to true. A special case is made for the version field, - -- which is only overwritten in the second object has more reliable version - -- information. The second object is not modified. + --- Merges the data from one SqlServerInstanceInfo object into another. + -- + -- Each field in the first object is populated with the data from that field + -- in second object if the first object's field is nil OR if + -- overwrite is set to true. A special case is made for the + -- version field, which is only overwritten in the second object + -- has more reliable version information. The second object is not modified. Merge = function( self, other, overwrite ) local mergeFields = { "host", "port", "instanceName", "version", "isClustered", "pipeName" } for _, fieldname in ipairs( mergeFields ) do @@ -227,8 +228,9 @@ SqlServerInstanceInfo = end end, - --- Returns a name for the instance, based on the available information. This - -- may take one of the following forms: + --- Returns a name for the instance, based on the available information. + -- + -- This may take one of the following forms: -- * HOST\INSTANCENAME -- * PIPENAME -- * HOST:PORT @@ -2144,6 +2146,7 @@ TDSStream = { end, --- Receives responses from SQL Server + -- -- The function continues to read and assemble a response until the server -- responds with the last response flag set -- @@ -2301,11 +2304,13 @@ Helper = end, --- Adds an instance to the list of instances kept in the Nmap registry for - -- shared use by SQL Server scripts. If the registry already contains the - -- instance, any new information is merged into the existing instance info. - -- This may happen, for example, when an instance is discovered via named - -- pipes, but the same instance has already been discovered via SSRP; this - -- will prevent duplicates, where possible. + -- shared use by SQL Server scripts. + -- + -- If the registry already contains the instance, any new information is + -- merged into the existing instance info. This may happen, for example, + -- when an instance is discovered via named pipes, but the same instance has + -- already been discovered via SSRP; this will prevent duplicates, where + -- possible. AddOrMergeInstance = function( newInstance ) local instanceExists @@ -2356,6 +2361,7 @@ Helper = --- Attempts to discover SQL Server instances using SSRP to query one or -- more (if broadcast is used) SQL Server Browser services. + -- -- Any discovered instances are returned, as well as being stored for use -- by other scripts (see mssql.Helper.GetDiscoveredInstances()). -- @@ -2413,8 +2419,11 @@ Helper = end, --- Attempts to discover a SQL Server instance listening on the specified - -- port. If an instance is discovered, it is returned, as well as being - -- stored for use by other scripts (see mssql.Helper.GetDiscoveredInstances()). + -- port. + -- + -- If an instance is discovered, it is returned, as well as being stored for + -- use by other scripts (see + -- mssql.Helper.GetDiscoveredInstances()). -- -- @param host A host table for the target. -- @param port A port table for the target port. @@ -2449,8 +2458,10 @@ Helper = end, --- Attempts to discover SQL Server instances listening on default named - -- pipes. Any discovered instances are returned, as well as being stored - -- for use by other scripts (see mssql.Helper.GetDiscoveredInstances()). + -- pipes. + -- + -- Any discovered instances are returned, as well as being stored for use by + -- other scripts (see mssql.Helper.GetDiscoveredInstances()). -- -- @param host A host table for the target. -- @param port A port table for the port to connect on for SMB @@ -2487,6 +2498,7 @@ Helper = end, --- Attempts to discover SQL Server instances by a variety of means. + -- -- This function calls the three DiscoverBy functions, which perform the -- actual discovery. Any discovered instances can be retrieved using -- mssql.Helper.GetDiscoveredInstances(). @@ -2563,6 +2575,7 @@ Helper = --- Returns a username-password set according to the following rules of -- precedence: + -- -- * If the mssql.username and mssql.password -- script arguments were set, their values are used. (If the username -- argument was specified without the password argument, a blank @@ -2616,8 +2629,9 @@ Helper = return true end, - --- Authenticates to SQL Server. If login fails, one of the following error - -- messages will be returned: + --- Authenticates to SQL Server. + -- + -- If login fails, one of the following error messages will be returned: -- * "Password is expired" -- * "Must change password at next logon" -- * "Account is locked out" @@ -2711,10 +2725,11 @@ Helper = end, --- Authenticates to SQL Server, using the credentials returned by - -- Helper.GetLoginCredentials(). If the login is rejected by the server, - -- the error code will be returned, as a number in the form of a - -- mssql.LoginErrorType (for which error messages can be - -- looked up in mssql.LoginErrorMessage). + -- Helper.GetLoginCredentials(). + -- + -- If the login is rejected by the server, the error code will be returned, + -- as a number in the form of a mssql.LoginErrorType (for which + -- error messages can be looked up in mssql.LoginErrorMessage). -- -- @param instanceInfo a SqlServerInstanceInfo object for the instance to log into -- @param database string containing the database to access @@ -2967,6 +2982,7 @@ Helper = end, --- Queries the SQL Browser service for the DAC port of the specified instance + -- -- The DAC (Dedicated Admin Connection) port allows DBA's to connect to -- the database when normal connection attempts fail, for example, when -- the server is hanging, out of memory or other bad states. @@ -3002,7 +3018,9 @@ Helper = --- Returns a hostrule for standard SQL Server scripts, which will return -- true if one or more instances have been targeted with the mssql.instance - -- script argument. However, if a previous script has failed to find any + -- script argument. + -- + -- However, if a previous script has failed to find any -- SQL Server instances on the host, the hostrule function will return -- false to keep further scripts from running unnecessarily on that host. -- @@ -3022,8 +3040,9 @@ Helper = end, - --- Returns a portrule for standard SQL Server scripts, which will run return - -- true if BOTH of the following conditions are met: + --- Returns a portrule for standard SQL Server scripts + -- + -- The portrule return true if BOTH of the following conditions are met: -- * The port has been identified as "ms-sql-s" -- * The mssql.instance script argument has NOT been used -- diff --git a/nselib/ncp.lua b/nselib/ncp.lua index cb610c012..083cb4d42 100644 --- a/nselib/ncp.lua +++ b/nselib/ncp.lua @@ -1012,10 +1012,12 @@ Helper = { --- Retrieves some information from the server using the following NCP -- functions: - -- GetFileServerInfo - -- Ping - -- EnumerateNetworkAddress - -- GetMountVolumeList + -- + -- * GetFileServerInfo + -- * Ping + -- * EnumerateNetworkAddress + -- * GetMountVolumeList + -- -- The result contains the Tree name, product versions and mounts getServerInfo = function(self) local status, srv_info = self.ncp:GetFileServerInfo() diff --git a/nselib/netbios.lua b/nselib/netbios.lua index 40c4f9886..d7db82f75 100644 --- a/nselib/netbios.lua +++ b/nselib/netbios.lua @@ -21,10 +21,12 @@ types = { NBSTAT = 33, } ---- Encode a NetBIOS name for transport. Most packets that use the NetBIOS name --- require this encoding to happen first. It takes a name containing any possible --- character, and converted it to all uppercase characters (so it can, for example, --- pass case-sensitive data in a case-insensitive way) +--- Encode a NetBIOS name for transport. +-- +-- Most packets that use the NetBIOS name require this encoding to happen +-- first. It takes a name containing any possible character, and converted it +-- to all uppercase characters (so it can, for example, pass case-sensitive +-- data in a case-insensitive way) -- -- There are two levels of encoding performed: -- * L1: Pad the string to 16 characters withs spaces (or NULLs if it's the @@ -82,9 +84,10 @@ end ---- Does the exact opposite of name_encode. Converts an encoded name to --- the string representation. If the encoding is invalid, it will still attempt --- to decode the string as best as possible. +--- Converts an encoded name to the string representation. +-- +-- If the encoding is invalid, it will still attempt to decode the string as +-- best as possible. --@param encoded_name The L2-encoded name --@return the decoded name and the scope. The name will still be padded, and the -- scope will never be nil (empty string is returned if no scope is present) @@ -178,10 +181,11 @@ function get_server_name(host, names) return false, "Couldn't find NetBIOS server name" end ---- Sends out a UDP probe on port 137 to get the user's name (that is, the --- entry in its NBSTAT table with a 0x03 suffix, that isn't the same as --- the server's name. If the username can't be determined, which is frequently --- the case, nil is returned. +--- Sends out a UDP probe on port 137 to get the user's name +-- +-- User name is the entry in its NBSTAT table with a 0x03 suffix, that isn't +-- the same as the server's name. If the username can't be determined, which is +-- frequently the case, nil is returned. --@param host The IP or hostname of the server. --@param names [optional] The names to use, from do_nbstat. --@return (status, result) If status is true, the result is the NetBIOS name or nil. @@ -214,8 +218,10 @@ end --- This is the function that actually handles the UDP query to retrieve --- the NBSTAT information. We make use of the Nmap registry here, so if another --- script has already performed a nbstat query, the result can be re-used. +-- the NBSTAT information. +-- +-- We make use of the Nmap registry here, so if another script has already +-- performed a nbstat query, the result can be re-used. -- -- The NetBIOS request's header looks like this: -- diff --git a/nselib/smb.lua b/nselib/smb.lua index a3717628a..630e89a60 100644 --- a/nselib/smb.lua +++ b/nselib/smb.lua @@ -245,9 +245,12 @@ function get_port(host) return nil end ----Turn off extended security negotiations for this connection. There are a few reasons you might want to --- do that, the main ones being that extended security is going to be marginally slower and it's not going --- to give the same level of information in some cases (namely, it doesn't present the server's name). +---Turn off extended security negotiations for this connection. +-- +-- There are a few reasons you might want to do that, the main ones being that +-- extended security is going to be marginally slower and it's not going to +-- give the same level of information in some cases (namely, it doesn't present +-- the server's name). --@param smb The SMB state table. function disable_extended(smb) smb['extended_security'] = false @@ -324,23 +327,29 @@ function start(host) return false, "SMB: Couldn't find a valid port to check" end ----Initiates a SMB connection over whichever port it can, then optionally sends the common --- initialization packets. Note that each packet depends on the previous one, so if you want --- to go all the way up to create_file, you have to set all parameters. +---Initiates a SMB connection over whichever port it can, then optionally sends +-- the common initialization packets. -- --- If anything fails, we back out of the connection and return an error, so the calling function --- doesn't have to call smb.stop(). +-- Note that each packet depends on the previous one, so if you want to go all +-- the way up to create_file, you have to set all parameters. -- ---@param host The host object. ---@param bool_negotiate_protocol [optional] If 'true', send the protocol negotiation. Default: false. ---@param bool_start_session [optional] If 'true', start the session. Default: false. ---@param str_tree_connect [optional] The tree to connect to, if given (eg. "IPC$" or "C$"). If not given, --- packet isn't sent. ---@param str_create_file [optional] The path and name of the file (or pipe) that's created, if given. If --- not given, packet isn't sent. ---@param overrides [optional] A table of overrides (for, for example, username, password, etc.) to pass --- to all functions. ---@param bool_disable_extended [optional] If set to true, disables extended security negotiations. +-- If anything fails, we back out of the connection and return an error, so the +-- calling function doesn't have to call smb.stop(). +-- +--@param host The host object. +--@param bool_negotiate_protocol [optional] If 'true', send the protocol +-- negotiation. Default: false. +--@param bool_start_session [optional] If 'true', start the session. Default: +-- false. +--@param str_tree_connect [optional] The tree to connect to, if given (eg. +-- "IPC$" or "C$"). If not given, packet isn't sent. +--@param str_create_file [optional] The path and name of the file (or pipe) +-- that's created, if given. If not given, packet isn't +-- sent. +--@param overrides [optional] A table of overrides (for, for example, username, +-- password, etc.) to pass to all functions. +--@param bool_disable_extended [optional] If set to true, disables extended +-- security negotiations. function start_ex(host, bool_negotiate_protocol, bool_start_session, str_tree_connect, str_create_file, bool_disable_extended, overrides) local smbstate local status, err @@ -475,24 +484,27 @@ local function get_subnames(name) return list end ---- Begins a SMB session over NetBIOS. This requires a NetBIOS Session Start message to --- be sent first, which in turn requires the NetBIOS name. The name can be provided as --- a parameter, or it can be automatically determined. +--- Begins a SMB session over NetBIOS. -- --- Automatically determining the name is interesting, to say the least. Here are the names --- it tries, and the order it tries them in: +-- This requires a NetBIOS Session Start message to be sent first, which in +-- turn requires the NetBIOS name. The name can be provided as a parameter, or +-- it can be automatically determined. +-- +-- Automatically determining the name is interesting, to say the least. Here +-- are the names it tries, and the order it tries them in: -- * The name the user provided, if present -- * The name pulled from NetBIOS (udp/137), if possible -- * The generic name "*SMBSERVER" --- * Each subset of the domain name (for example, scanme.insecure.org would attempt "scanme", --- "scanme.insecure", and "scanme.insecure.org") +-- * Each subset of the domain name (for example, scanme.insecure.org would +-- attempt "scanme", "scanme.insecure", and "scanme.insecure.org") -- --- This whole sequence is a little hackish, but it's the standard way of doing it. +-- This whole sequence is a little hackish, but it's the standard way of doing +-- it. -- --@param host The host object to check. --@param port The port to use (most likely 139). ---@param name [optional] The NetBIOS name of the host. Will attempt to automatically determine --- if it isn't given. +--@param name [optional] The NetBIOS name of the host. Will attempt to +-- automatically determine if it isn't given. --@return (status, socket) if status is true, result is the port -- Otherwise, socket is the error message. function start_netbios(host, port, name) @@ -678,7 +690,9 @@ function smb_encode_header(smb, command, overrides) return header end ---- Converts a string containing the parameters section into the encoded parameters string. +--- Converts a string containing the parameters section into the encoded +-- parameters string. +-- -- The encoding is simple: -- * (1 byte) The number of 2-byte values in the parameters section -- * (variable) The parameter section @@ -695,6 +709,7 @@ local function smb_encode_parameters(parameters, overrides) end --- Converts a string containing the data section into the encoded data string. +-- -- The encoding is simple: -- * (2 bytes) The number of bytes in the data section -- * (variable) The data section @@ -737,9 +752,10 @@ local function message_sign(smb, body) return string.sub(body, 1, 14) .. signature .. string.sub(body, 23) end ----Check the signature of the message. This is the opposite of message_sign, --- and works the same way (replaces the signature with the sequence number, calculates --- hash, checks) +---Check the signature of the message. +-- +-- This is the opposite of message_sign, and works the same way +-- (replaces the signature with the sequence number, calculates hash, checks) --@param smb The smb state object. --@param body The body of the packet that's being checked. --@return A true/false value -- true if the packet was signed properly, false if it wasn't. @@ -773,8 +789,10 @@ local function message_check_signature(smb, body) end --- Prepends the NetBIOS header to the packet, which is essentially the length, encoded --- in 4 bytes of big endian, and sends it out. The length field is actually 17 or 24 bits --- wide, depending on whether or not we're using raw, but that shouldn't matter. +-- in 4 bytes of big endian, and sends it out. +-- +-- The length field is actually 17 or 24 bits wide, depending on whether or +-- not we're using raw, but that shouldn't matter. -- --@param smb The SMB object associated with the connection --@param header The header, encoded with smb_get_header. @@ -924,6 +942,7 @@ function smb_read(smb, read_data) end --- Sends out SMB_COM_NEGOTIATE, which is typically the first SMB packet sent out. +-- -- Sends the following: -- * List of known protocols -- @@ -1496,6 +1515,7 @@ local function start_session_extended(smb, log_errors, overrides) end --- Sends out SMB_COM_SESSION_SETUP_ANDX, which attempts to log a user in. +-- -- Sends the following: -- * Negotiated parameters (multiplexed connections, virtual circuit, capabilities) -- * Passwords (plaintext, unicode, lanman, ntlm, lmv2, ntlmv2, etc) @@ -1534,7 +1554,9 @@ function start_session(smb, overrides, log_errors) return status, result end ---- Sends out SMB_COM_SESSION_TREE_CONNECT_ANDX, which attempts to connect to a share. +--- Sends out SMB_COM_SESSION_TREE_CONNECT_ANDX, which attempts to +-- connect to a share. +-- -- Sends the following: -- * Password (for share-level security, which we don't support) -- * Share name @@ -1705,8 +1727,10 @@ function logoff(smb, overrides) end --- This sends a SMB request to open or create a file. --- Most of the parameters I pass here are used directly from a packetlog, especially the various permissions fields and flags. --- I might make this more adjustable in the future, but this has been working for me. +-- +-- Most of the parameters I pass here are used directly from a packetlog, +-- especially the various permissions fields and flags. I might make this +-- more adjustable in the future, but this has been working for me. -- --@param smb The SMB object associated with the connection --@param path The path of the file or pipe to open @@ -2183,23 +2207,31 @@ end ----This is the core of making MSRPC calls. It sends out a MSRPC packet with the given parameters and data. --- Don't confuse these parameters and data with SMB's concepts of parameters and data -- they are completely --- different. In fact, these parameters and data are both sent in the SMB packet's 'data' section. +---This is the core of making MSRPC calls. It sends out a MSRPC packet with the +-- given parameters and data. -- --- It is probably best to think of this as another protocol layer. This function will wrap SMB stuff around a --- MSRPC call, make the call, then unwrap the SMB stuff from it before returning. +-- Don't confuse these parameters and data with SMB's concepts of parameters +-- and data -- they are completely different. In fact, these parameters and +-- data are both sent in the SMB packet's 'data' section. -- ---@param smb The SMB object associated with the connection ---@param function_parameters The parameter data to pass to the function. This is untested, since none of the --- transactions I've done have required parameters. ---@param function_data The data to send with the packet. This is basically the next protocol layer ---@param pipe [optional] The pipe to transact on. Default: "\PIPE\". ---@param no_setup [optional] If set, the 'setup' is set to 0 and some parameters are left off. This occurs while --- using the LANMAN Remote API. Default: false. ---@param overrides The overrides table ---@return (status, result) If status is false, result is an error message. Otherwise, result is a table --- containing 'parameters' and 'data', representing the parameters and data returned by the server. +-- It is probably best to think of this as another protocol layer. This +-- function will wrap SMB stuff around a MSRPC call, make the call, then unwrap +-- the SMB stuff from it before returning. +-- +--@param smb The SMB object associated with the connection +--@param function_parameters The parameter data to pass to the function. This +-- is untested, since none of the transactions I've +-- done have required parameters. +--@param function_data The data to send with the packet. This is basically the +-- next protocol layer +--@param pipe [optional] The pipe to transact on. Default: "\PIPE\". +--@param no_setup [optional] If set, the 'setup' is set to 0 and some +-- parameters are left off. This occurs while using the LANMAN +-- Remote API. Default: false. +--@param overrides The overrides table +--@return (status, result) If status is false, result is an error message. +-- Otherwise, result is a table containing 'parameters' and 'data', +-- representing the parameters and data returned by the server. function send_transaction_named_pipe(smb, function_parameters, function_data, pipe, no_setup, overrides) overrides = overrides or {} local header1, header2, header3, header4, command, status, flags, flags2, pid_high, signature, unused, pid, mid @@ -3355,17 +3387,25 @@ function get_socket_info(host) return true, lhost, lport, rhost, rport, lmac end ----Generate a string that's somewhat unique, but is based on factors that won't change on a host. At the moment, this is a very simple --- hash based on the IP address. This hash is *very* likely to have collisions, and that's by design -- while it should be somewhat unique, --- I don't want it to be trivial to uniquely determine who it originated from. +---Generate a string that's somewhat unique, but is based on factors that won't +-- change on a host. -- --- TODO: At some point, I should re-do this function properly, with a method of hashing that's somewhat proven. +-- At the moment, this is a very simple hash based on the IP address. This hash +-- is *very* likely to have collisions, and that's by design -- while it should +-- be somewhat unique, I don't want it to be trivial to uniquely determine who +-- it originated from. +-- +-- TODO: At some point, I should re-do this function properly, with a method of +-- hashing that's somewhat proven. -- --@param host The host object ---@param extension [optional] The extension to add on the end of the file. Default: none. ---@param seed [optional] Some randomness on which to base the name. If you want to do multiple files, each with its --- own uniqueish name, this can be used. ---@return (status, data) If status is true, data is a table of values; otherwise, data is an error message. Can be any kind of string. +--@param extension [optional] The extension to add on the end of the file. +-- Default: none. +--@param seed [optional] Some randomness on which to base the name. If you want +-- to do multiple files, each with its own uniqueish name, this can +-- be used. +--@return (status, data) If status is true, data is a table of values; +-- otherwise, data is an error message. Can be any kind of string. function get_uniqueish_name(host, extension, seed) local status diff --git a/nselib/smtp.lua b/nselib/smtp.lua index bf6ddb852..faea2e5c9 100644 --- a/nselib/smtp.lua +++ b/nselib/smtp.lua @@ -159,11 +159,12 @@ local SMTP_CMD = { }, } --- --- Returns a domain to be used in the SMTP commands that need it. If the --- user specified one through the script argument smtp.domain --- this function will return it. Otherwise it will try to find the domain --- from the typed hostname and from the rDNS name. If it still can't find --- one it will return the nmap.scanme.org by default. +-- Returns a domain to be used in the SMTP commands that need it. +-- +-- If the user specified one through the script argument +-- smtp.domain this function will return it. Otherwise it will try +-- to find the domain from the typed hostname and from the rDNS name. If it +-- still can't find one it will return the nmap.scanme.org by default. -- -- @param host The host table -- @return The hostname to be used by the different SMTP commands. diff --git a/nselib/stdnse.lua b/nselib/stdnse.lua index cc80628c8..32acc88df 100644 --- a/nselib/stdnse.lua +++ b/nselib/stdnse.lua @@ -330,8 +330,10 @@ end --- -- Parses a time duration specification, which is a number followed by a --- unit, and returns a number of seconds. The unit is optional and --- defaults to seconds. The possible units (case-insensitive) are +-- unit, and returns a number of seconds. +-- +-- The unit is optional and defaults to seconds. The possible units +-- (case-insensitive) are -- * ms: milliseconds, -- * s: seconds, -- * m: minutes, @@ -385,12 +387,13 @@ local function utc_offset(t) -- Interpret both as local calendar dates and find the difference. return difftime(os.time(localtime), os.time(gmtime)) end ---- Convert a date table into an integer timestamp. Unlike os.time, this does --- not assume that the date table represents a local time. Rather, it takes an --- optional offset number of seconds representing the time zone, and returns --- the timestamp that would result using that time zone as local time. If the --- offset is omitted or 0, the date table is interpreted as a UTC date. For --- example, 4:00 UTC is the same as 5:00 UTC+1: +--- Convert a date table into an integer timestamp. +-- +-- Unlike os.time, this does not assume that the date table represents a local +-- time. Rather, it takes an optional offset number of seconds representing the +-- time zone, and returns the timestamp that would result using that time zone +-- as local time. If the offset is omitted or 0, the date table is interpreted +-- as a UTC date. For example, 4:00 UTC is the same as 5:00 UTC+1: -- -- date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}) --> 14400 -- date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}, 0) --> 14400 @@ -658,7 +661,9 @@ local function format_output_sub(status, data, indent) end ---Takes a table of output on the commandline and formats it for display to the --- user. This is basically done by converting an array of nested tables into a +-- user. +-- +-- This is basically done by converting an array of nested tables into a -- string. In addition to numbered array elements, each table can have a 'name' -- and a 'warning' value. The 'name' will be displayed above the table, and -- 'warning' will be displayed, with a 'WARNING' tag, if and only if debugging @@ -837,6 +842,7 @@ function registry_exists(subkeys, key, value) end ---Add an item to an array in the registry, creating all sub-keys if necessary. +-- -- For example, calling: -- registry_add_array({'192.168.1.100', 'www', '80', 'pages'}, 'index.html') -- Will create nmap.registry['192.168.1.100'] as a table, if necessary, then add a table @@ -1012,6 +1018,7 @@ do end -- no function here, see nse_main.lua ---Checks if the port is in the port range +-- -- For example, calling: -- in_port_range({number=31337,protocol="udp"},"T:15,50-75,U:31334-31339") -- would result in a true value @@ -1211,8 +1218,12 @@ end local FILESYSTEM_UNSAFE = "[^a-zA-Z0-9._-]" --- -- Escape a string to remove bytes and strings that may have meaning to --- a filesystem, such as slashes. All bytes are escaped, except for: --- * alphabetic a-z and A-Z, digits 0-9, . _ - +-- a filesystem, such as slashes. +-- +-- All bytes are escaped, except for: +-- * alphabetic a-z and A-Z +-- * digits 0-9 +-- * . _ - -- In addition, the strings "." and ".." have -- their characters escaped. -- diff --git a/nselib/tftp.lua b/nselib/tftp.lua index 2f81e99a1..2050c74d7 100644 --- a/nselib/tftp.lua +++ b/nselib/tftp.lua @@ -314,9 +314,10 @@ local function waitLast() end --- Waits for a file with a specific filename for at least the number of --- seconds specified by the timeout parameter. If this function is called --- from the thread that's running the server it will wait until all the --- other threads have finished executing before returning. +-- seconds specified by the timeout parameter. +-- +-- If this function is called from the thread that's running the server it will +-- wait until all the other threads have finished executing before returning. -- -- @param filename string containing the name of the file to receive -- @param timeout number containing the minimum number of seconds to wait diff --git a/nselib/unicode.lua b/nselib/unicode.lua index af43f0051..c237937d0 100644 --- a/nselib/unicode.lua +++ b/nselib/unicode.lua @@ -56,6 +56,7 @@ function encode(list, encoder, bigendian) end ---Encode a Unicode code point to UTF-16. See RFC 2781. +-- -- Windows OS prior to Windows 2000 only supports UCS-2, so beware using this -- function to encode code points above 0xFFFF. --@param cp The Unicode code point as a number @@ -82,6 +83,7 @@ function utf16_enc(cp, bigendian) end ---Decodes a UTF-16 character. +-- -- Does not check that the returned code point is a real character. -- Specifically, it can be fooled by out-of-order lead- and trail-surrogate -- characters. @@ -108,6 +110,7 @@ function utf16_dec(buf, pos, bigendian) end ---Encode a Unicode code point to UTF-8. See RFC 3629. +-- -- Does not check that cp is a real character; that is, doesn't exclude the -- surrogate range U+D800 - U+DFFF and a handful of others. --@param cp The Unicode code point as a number @@ -146,6 +149,7 @@ function utf8_enc(cp) end ---Decodes a UTF-8 character. +-- -- Does not check that the returned code point is a real character. --@param buf A string containing the character --@param pos The index in the string where the character begins diff --git a/nselib/upnp.lua b/nselib/upnp.lua index 0f84b839a..174ce149c 100644 --- a/nselib/upnp.lua +++ b/nselib/upnp.lua @@ -115,7 +115,9 @@ Comm = { end, --- Receives one or multiple UPNP responses depending on whether - -- setBroadcast was enabled or not. The function returns the + -- setBroadcast was enabled or not. + -- + -- The function returns the -- status and a response containing: -- * an array (table) of responses if broadcast is used -- * a single response if broadcast is not in use diff --git a/nselib/vnc.lua b/nselib/vnc.lua index 79b92d373..005d98cd6 100644 --- a/nselib/vnc.lua +++ b/nselib/vnc.lua @@ -109,8 +109,8 @@ VNC = { end, --- Performs the VNC handshake and determines - -- o The RFB Protocol to use - -- o The supported authentication security types + -- * The RFB Protocol to use + -- * The supported authentication security types -- -- @return status, true on success, false on failure -- @return error string containing error message if status is false