PenTest/nmap
1
0
Fork 0
mirror of https://github.com/nmap/nmap.git synced 2025-12-06 12:41:29 +00:00
Code Issues Projects Releases Wiki Activity

NSEdoc cleanup.

Browse Source 
1. The first paragraph of a function's NSEdoc is used as a short
summary. Some of these were very long, so I split off a shorter summary.

2. Use asterisks (*) to denote bulletted lists, not 'o'

3. Wrap lines at 80 columns

4. a couple other spelling and formatting fixes
This commit is contained in:
dmiller
2014-03-10 19:01:19 +00:00
parent e0a0b616b4
commit 17c3e9755e
23 changed files with 709 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
nselib/amqp.lua
View File

@@ -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

10
nselib/asn1.lua
View File

@@ -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 <code>BERCLASS<code>

16
nselib/bittorrent.lua
View File

@@ -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://(.-):(.+)")

12
nselib/dhcp.lua
View File

@@ -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 (<code>actions</code>) 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 (<code>actions</code>) 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 = {}

7
nselib/dns.lua
View File

@@ -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)

2
nselib/formulas.lua
View File

@@ -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

230
nselib/http.lua
View File

@@ -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 <code>generic_request</code>, 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 <code>redirect_ok</code> 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 <code>generic_request</code>, 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 <code>redirect_ok</code> 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 <code>MAX_REDIRECT_COUNT</code> count of redirects
--
-- Caching and redirects can be controlled in the <code>options</code> array, see module
-- documentation for more information.
-- Caching and redirects can be controlled in the <code>options</code> 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 <code>get</code>, this is a simple
-- wrapper around <code>generic_request</code> 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 <code>redirect_ok</code> field
-- of the options array. The default function redirects the request if the
-- destination is:
---Fetches a resource with a HEAD request.
--
-- Like <code>get</code>, this is a simple wrapper around
-- <code>generic_request</code> 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 <code>redirect_ok</code>
-- 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 <code>get</code>, this is a simple
-- wrapper around <code>generic_request</code> except that postdata is handled
-- properly.
---Fetches a resource with a POST request.
--
-- Like <code>get</code>, this is a simple wrapper around
-- <code>generic_request</code> 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 <code>all_requests</code> argument contains the current list of queued requests (if this
-- is the first time calling <code>pipeline_add</code>, it should be <code>nil</code>). 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 <code>all_requests</code> argument contains the current list of queued
-- requests (if this is the first time calling <code>pipeline_add</code>, it
-- should be <code>nil</code>). After adding the request to end of the queue,
-- the queue is returned and can be passed to the next
-- <code>pipeline_add</code> call.
--
-- When all requests have been queued, call <code>pipeline_go</code> with the all_requests table
-- that has been built.
-- When all requests have been queued, call <code>pipeline_go</code> 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 <code>add_pipeline</code> 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 <code>add_pipeline</code> 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
-- <code>pipeline_add</code> function). Returns an array of responses, each of
-- which is a table as defined in the module documentation above.
-- <code>pipeline_add</code> 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 <code>response.body</code> 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 <code>asctime()</code> 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 <code>scheme</code> and
-- <code>params</code>.
-- and RFC 2617, section 1.2.
--
-- The return value is an array of challenges. Each challenge is a table with
-- the keys <code>scheme</code> and <code>params</code>.
-- @param s The header value text.
-- @return An array of challenges, or <code>nil</code> 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 <code>identify_404</code> 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 <code>identify_404</code>. If the 404 page returns a
-- 200 code, then we disable HEAD requests.
-- This is returned by <code>identify_404</code>. 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
--<code>identify_404</code>, 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 <code>identify_404</code>, 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 <code>identify_404</code>.
-- @param known_404 The 404 page itself, if <code>result_404</code> is 200. If <code>result_404</code> is something else, this parameter is ignored and can be set to <code>nil</code>. This is returned by <code>identify_404</code>.
-- @param result_404 The status code to expect for non-existent pages. This is
-- returned by <code>identify_404</code>.
-- @param known_404 The 404 page itself, if <code>result_404</code> is 200. If
-- <code>result_404</code> is something else, this parameter
-- is ignored and can be set to <code>nil</code>. This is
-- returned by <code>identify_404</code>.
-- @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 <code>true</code> 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 <code>true</code> 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.

2
nselib/informix.lua
View File

@@ -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

19
nselib/ipOps.lua
View File

@@ -214,13 +214,16 @@ 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: <code>"eq"</code>, <code>"ge"</code>, <code>"le"</code>,
-- <code>"gt"</code> or <code>"lt"</code> (respectively ==, >=, <=, >, <).
-- @param op A comparison operator which may be one of the following strings:
-- <code>"eq"</code>, <code>"ge"</code>, <code>"le"</code>,
-- <code>"gt"</code> or <code>"lt"</code> (respectively ==, >=, <=,
-- >, <).
-- @param right String representing an IPv4 or IPv6 address. Shortened
-- notation is permitted.
-- @usage
@@ -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 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 <code>nil</code> in case of an error).
-- @return String representing the last IP address of the range denoted by the
-- supplied parameters (or <code>nil</code> in case of an error).
-- @return String error message in case of an error.
get_last_ip = function( ip, prefix )

11
nselib/json.lua
View File

@@ -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
-- @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
-- @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

189
nselib/msrpc.lua
View File

@@ -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 <code>bind</code> 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 <code>bind</code> 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 <code>smb.stop</code> 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 <code>smb.stop</code> 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 <code>SMB_COM_TRANSACTION</code> 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
-- <code>SMB_COM_TRANSACTION</code> 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.
--
-- 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 <code>bind</code> 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.
--@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 <code>msrpctypes</code> 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 <code>msrpctypes</code>
-- functions.
---A proxy to a <code>msrpctypes</code> 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
-- <code>msrpctypes</code> 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 <code>netshareenumall</code> on the remote system. This function basically returns a list of all the shares
-- on the system.
---Call the MSRPC function <code>netshareenumall</code> 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 <code>msrpctypes</code> 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 <code>msrpctypes</code>
-- functions.
---A proxy to a <code>msrpctypes</code> 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
-- <code>msrpctypes</code> 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 <code>msrpctypes</code> 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 <code>msrpctypes</code>
-- functions.
---A proxy to a <code>msrpctypes</code> 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
-- <code>msrpctypes</code> 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 <code>connect4</code> function, to obtain a "connect handle". This must be done before calling many
-- of the SAMR functions.
---Call the <code>connect4</code> function, to obtain a "connect handle".
--
-- 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, 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.
--@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 <code>msrpctypes</code> 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 <code>msrpctypes</code>
-- functions.
---A proxy to a <code>msrpctypes</code> 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
-- <code>msrpctypes</code> 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 <code>JobAdd</code>, 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 <code>JobAdd</code>, 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 <code>smbstate</code>
-- 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
-- <code>smbstate</code> 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 <code>false</code>, <code>err</code> 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.
---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.
--@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

15
nselib/msrpcperformance.lua
View File

@@ -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 <code>result['title_database']</code> -- 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
-- <code>result['title_database']</code> -- 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

256
nselib/msrpctypes.lua
View File

@@ -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 <code>func</code> is called, which is passed as
-- a parameter, with the arguments <code>args</code>. 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 <code>func</code> doesn't have to conform to any special prototype,
-- as long as the <code>args</code> array matches what the function wants.
-- When marshalling the body, the function <code>func</code> is called, which
-- is passed as a parameter, with the arguments <code>args</code>. 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 <code>func</code> doesn't have to conform to any
-- special prototype, as long as the <code>args</code> array matches what the
-- function wants.
--
-- This can be used to marshall an int16 value of 0x1234 with padding like this:
-- <code>
@@ -224,15 +232,16 @@ end
-- marshall_ptr(ALL, marshall_unicode, {str, true}, str)
-- </code>
--
--@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 <code>args</code> parameter to a string.
--@param args An array of arguments that will be directly passed to the function <code>func</code>
--@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 <code>args</code> parameter to a string.
--@param args An array of arguments that will be directly passed to the
-- function <code>func</code>
--@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 <code>result</code>
-- 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 <code>result</code> parameter, it is the result from the first time
-- this is called.
--
-- The function <code>func</code> has to conform to this format:
--<code>
-- func(data, pos, <args>)
--</code>
--
--@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 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 <code>data</code>
--@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 <code>func</code>, 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
--@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
-- <code>func</code>, 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 <code>true</code>
-- for valid pointers or <code>false</code> for null pointers. For BODY or ALL, the result is
-- <code>nil</code> for null pointers, or the data for valid pointers.
--@return The new position
--@reutrn The result. For HEAD the result is either <code>true</code> for valid
-- pointers or <code>false</code> for null pointers. For BODY or ALL,
-- the result is <code>nil</code> 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 <code>marshall_ptr</code>, 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 <code>marshall_srvsvc_NetShareInfo2</code>).
-- 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 <code>marshall_ptr</code>, 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
-- <code>marshall_srvsvc_NetShareInfo2</code>).
--
--@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 <code>marshall_ptr</code>, 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 <code>args</code> parameter to a string.
--@param args An array of arguments that will be directly passed to the function <code>func</code>
--@param func The function to call when encoding the body. Should convert the
-- arguments passed in the <code>args</code> parameter to a string.
--@param args An array of arguments that will be directly passed to the
-- function <code>func</code>
--@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:
--<code>
-- func(location, <args>)
--</code>
-- 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 <code>func</code> has to conform to a very specific prototype:
--<code>
-- func(location, data, pos, result, <args>)
--</code>
-- Where <code>location<code> is the standard HEAD/BODY location, <code>data<code> and <code>pos<code>
-- are the packet and position within it, <code>result<code> is the result from the HEAD section (if
-- it's nil, it isn't used), and <code>args<code> are arbitrary arguments passed to it.
-- Where <code>location<code> is the standard HEAD/BODY location,
-- <code>data<code> and <code>pos<code> are the packet and position within it,
-- <code>result<code> is the result from the HEAD section (if it's nil, it
-- isn't used), and <code>args<code> 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 <code>data</code>.
--@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 <code>unmarshall_array</code>. This allows the same
-- struct to be used in <code>unmarshall_array</code> and in <code>unmarshall_ptr</code>. 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 <code>unmarshall_array</code>.
--
-- The <code>func</code> parameter, obviously, has to match the same prototype as strings being passed to
-- <code>unmarshall_array</code>, which is:
-- This allows the same struct to be used in <code>unmarshall_array</code> and
-- in <code>unmarshall_ptr</code>. 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 <code>func</code> parameter, obviously, has to match the same prototype
-- as strings being passed to <code>unmarshall_array</code>, which is:
--<code>
-- func(location, data, pos, result, <args>)
--</code>
--
--@param data The data being processed.
--@param pos The position within <code>data</code>.
--@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:
-- <code> [in,out] uint32 *ptr</code>
--
-- 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:
-- <code> [in,out] uint16 *ptr</code>
--
-- 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:
-- <code> [in,out] uint8 *ptr</code>
--
-- 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 <code>hyper</code>. I have no idea what a <code>hyper</code> 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 <code>hyper</code>.
--
-- I have no idea what a <code>hyper</code> 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
-- <code>table</code> 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
-- <code>table</code> 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
-- <code>table</code> 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
-- <code>table</code> 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)

71
nselib/mssql.lua
View File

@@ -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 <code>overwrite</code>
-- is set to true. A special case is made for the <code>version</code> 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
-- <code>overwrite</code> is set to true. A special case is made for the
-- <code>version</code> 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 <code>broadcast</code> is used) SQL Server Browser services.
--
-- Any discovered instances are returned, as well as being stored for use
-- by other scripts (see <code>mssql.Helper.GetDiscoveredInstances()</code>).
--
@@ -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 <code>mssql.Helper.GetDiscoveredInstances()</code>).
-- port.
--
-- If an instance is discovered, it is returned, as well as being stored for
-- use by other scripts (see
-- <code>mssql.Helper.GetDiscoveredInstances()</code>).
--
-- @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 <code>mssql.Helper.GetDiscoveredInstances()</code>).
-- pipes.
--
-- Any discovered instances are returned, as well as being stored for use by
-- other scripts (see <code>mssql.Helper.GetDiscoveredInstances()</code>).
--
-- @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
-- <code>mssql.Helper.GetDiscoveredInstances()</code>.
@@ -2563,6 +2575,7 @@ Helper =
--- Returns a username-password set according to the following rules of
-- precedence:
--
-- * If the <code>mssql.username</code> and <code>mssql.password</code>
-- 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
-- <code>mssql.LoginErrorType</code> (for which error messages can be
-- looked up in <code>mssql.LoginErrorMessage</code>).
-- Helper.GetLoginCredentials().
--
-- If the login is rejected by the server, the error code will be returned,
-- as a number in the form of a <code>mssql.LoginErrorType</code> (for which
-- error messages can be looked up in <code>mssql.LoginErrorMessage</code>).
--
-- @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 <code>mssql.instance</code>
-- 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 <code>mssql.instance</code> script argument has NOT been used
--

10
nselib/ncp.lua
View File

@@ -1012,10 +1012,12 @@ Helper = {
--- Retrieves some information from the server using the following NCP
-- functions:
-- <code>GetFileServerInfo</code>
-- <code>Ping</code>
-- <code>EnumerateNetworkAddress</code>
-- <code>GetMountVolumeList</code>
--
-- * <code>GetFileServerInfo</code>
-- * <code>Ping</code>
-- * <code>EnumerateNetworkAddress</code>
-- * <code>GetMountVolumeList</code>
--
-- The result contains the Tree name, product versions and mounts
getServerInfo = function(self)
local status, srv_info = self.ncp:GetFileServerInfo()

32
nselib/netbios.lua
View File

@@ -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 <code>do_nbstat</code>.
--@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:
--<code>

152
nselib/smb.lua
View File

@@ -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.
--
-- 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.
--@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 <code>message_sign</code>,
-- 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 <code>message_sign</code>, 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 <code>smb_get_header</code>.
@@ -924,6 +942,7 @@ function smb_read(smb, read_data)
end
--- Sends out <code>SMB_COM_NEGOTIATE</code>, 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 <code>SMB_COM_SESSION_TREE_CONNECT_ANDX</code>, which attempts to connect to a share.
--- Sends out <code>SMB_COM_SESSION_TREE_CONNECT_ANDX</code>, 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.
--
-- 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 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 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.
--@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

11
nselib/smtp.lua
View File

@@ -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 <code>smtp.domain</code>
-- 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
-- <code>smtp.domain</code> 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.

33
nselib/stdnse.lua
View File

@@ -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
-- * <code>ms</code>: milliseconds,
-- * <code>s</code>: seconds,
-- * <code>m</code>: 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:
-- <code>
-- 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:
-- <code>registry_add_array({'192.168.1.100', 'www', '80', 'pages'}, 'index.html')</code>
-- 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:
-- <code>in_port_range({number=31337,protocol="udp"},"T:15,50-75,U:31334-31339")</code>
-- 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 <code>a</code>-<code>z</code> and <code>A</code>-<code>Z</code>, digits 0-9, <code>.</code> <code>_</code> <code>-</code>
-- a filesystem, such as slashes.
--
-- All bytes are escaped, except for:
-- * alphabetic <code>a</code>-<code>z</code> and <code>A</code>-<code>Z</code>
-- * digits 0-9
-- * <code>.</code> <code>_</code> <code>-</code>
-- In addition, the strings <code>"."</code> and <code>".."</code> have
-- their characters escaped.
--

7
nselib/tftp.lua
View File

@@ -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

4
nselib/unicode.lua
View File

@@ -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

4
nselib/upnp.lua
View File

@@ -115,7 +115,9 @@ Comm = {
end,
--- Receives one or multiple UPNP responses depending on whether
-- <code>setBroadcast</code> was enabled or not. The function returns the
-- <code>setBroadcast</code> 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

4
nselib/vnc.lua
View File

@@ -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