diff --git a/docs/scripting.xml b/docs/scripting.xml index ef627ad50..584c7d82a 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -1428,58 +1428,6 @@ if(s) code_to_be_done_on_match end - - Short Portrules - shortport NSE module - - Since portrules are mostly the same for many scripts, the - shortport module provides functions for the most common tests. - The arguments in brackets ([]) are optional. If no - proto is provided, tcp is used. The default - state is open - - - - - - - - The port argument is either a number or a table of numbers which are - interpreted as port numbers, against which the script should run. - - - - - - - - - The service argument is either a string or a table - of strings which are interpreted as service names - (e.g. "http", "https", "smtp" or "ftp") against which the - script should run. These service names are - determined by Nmap's version scan or (if no version - scan information is available) the service assigned - to the port in nmap-services - (e.g. "http" for TCP port 80). - - - - - - - - - This is a combination of the above functions, since many scripts - explicitly try to run against the well-known ports, but want - also to run against any other port which was discovered to run the - named service. A typical example for this function is: - portrule = shortport.port_or_service(22,"ssh"). - - - - - String Buffer Operations strbuf NSE module @@ -1664,108 +1612,6 @@ if(s) code_to_be_done_on_match end - - - Various Utility Functions - stdnse NSE module - - The stdnse library contains various handy - functions which are too small to justify modules of their own: - - - - - - - - Wrapper function around print_debug_unformatted() - in the nmap namespace. The first optional numeric - argument, verbosity, is - used as the necessary debug level to print the message (it defaults - to 1 if omitted). All remaining arguments are processed with - Lua's string.format() function, which provides a - C-style printf interface. - - - - - - - - - This function will certainly be appreciated by Perl programmers. - It takes two strings as arguments and splits the second one around - all occurrences of the first one, returning a list (table), which - contains the substrings without the delimiting string. - - - - - - - - - Inverse function to strsplit(). Basically this is - Lua's table.concat() function with the parameters - swapped for coherence. - - - - - - - - - Converts the given number, n, to a string - in a binary number format (e.g. 5 becomes "101"). - - - - - - - - - Converts the given number, n, to a string - in an octal number format (e.g. 9 becomes "11"). - - - - - - - - - Converts the given number or string, s, to a - string in a hexadecimal number format (e.g. 10 becomes "a"). - options is a table containing parameters to - control the formatting. You may specify options.separator - which will be used as separator for groups of consecutive bytes. - With options.group you can control the group - length to be used with options.separator. - - - - - - - - - This function operates on a socket attempting to read data. - It separates the data by sep and, for each - invocation, returns a piece of the separated data. Typically - this is used to iterate over the lines of data received from a - socket (sep = "\r?\n"). The returned string - does not include the separator. It will return the final data - even if it is not followed by the separator. Once an error or - EOF is reached, it returns nil, msg. - msg is what is returned by - nmap.receive_lines(). - - - - - diff --git a/nselib/msrpc.lua b/nselib/msrpc.lua index f1e7848c0..fbdd649b0 100644 --- a/nselib/msrpc.lua +++ b/nselib/msrpc.lua @@ -1,4 +1,6 @@ ---- By making heavy use of the 'smb' library, this library will call various MSRPC +--- Call various MSRPC functions. +-- \n\n +-- By making heavy use of the smb library, this library will call various MSRPC -- functions. The functions used here can be access over TCP ports 445 and 139, -- with an established session. A NULL session (the default) will work for some -- functions and operating systems (or configurations), but not for others. \n diff --git a/nselib/pop3.lua b/nselib/pop3.lua index 1ce8c1106..29d7c3589 100644 --- a/nselib/pop3.lua +++ b/nselib/pop3.lua @@ -1,4 +1,4 @@ ---- POP3 functions +--- POP3 functions. --@copyright See nmaps COPYING for licence module(... or "pop3",package.seeall) @@ -24,9 +24,9 @@ err = { } --- --- Checks POP3 response for ---@param line First line returned from an POP3 request ---@return Found "+OK" string or nil +-- Check a POP3 response for "+OK". +--@param line First line returned from an POP3 request. +--@return Found "+OK" string or nil. function stat(line) return string.match(line, "+OK") end @@ -34,11 +34,11 @@ end --- --- Try to login using USER/PASS commands ---@param socket Socket connected to POP3 server ---@param user User string ---@param pw Password string ---@return Success as boolean and error code as in err table +-- Try to log in using USER/PASS commands. +--@param socket Socket connected to POP3 server. +--@param user User string. +--@param pw Password string. +--@return Success as boolean and error code as in err table. function login_user(socket, user, pw) socket:send("USER " .. user .. "\r\n") status, line = socket:receive_lines(1) @@ -54,11 +54,11 @@ end --- --- Try to login using AUTH command using SASL/Plain method ---@param socket Socket connected to POP3 server ---@param user User string ---@param pw Password string ---@return Success as boolean and error code as in err table +-- Try to login using AUTH command using SASL/Plain method. +--@param socket Socket connected to POP3 server. +--@param user User string. +--@param pw Password string. +--@return Success as boolean and error code as in err table. function login_sasl_plain(socket, user, pw) local auth64 = base64.enc(user .. "\0" .. user .. "\0" .. pw) @@ -74,11 +74,11 @@ function login_sasl_plain(socket, user, pw) end --- --- Try to login using AUTH command using SASL/Login method ---@param user User string ---@param pw Password string ---@param pw String containing password to login ---@return Success as boolean and error code as in err table +-- Try to login using AUTH command using SASL/Login method. +--@param user User string. +--@param pw Password string. +--@param pw String containing password to login. +--@return Success as boolean and error code as in err table. function login_sasl_login(socket, user, pw) local user64 = base64.enc(user) @@ -112,12 +112,12 @@ function login_sasl_login(socket, user, pw) end --- --- Try to login using APOP command ---@param socket Socket connected to POP3 server ---@param user User string ---@param pw Password string ---@param challenge String containing challenge from POP3 server greeting ---@return Success as boolean and error code as in err table +-- Try to login using APOP command. +--@param socket Socket connected to POP3 server. +--@param user User string. +--@param pw Password string. +--@param challenge String containing challenge from POP3 server greeting. +--@return Success as boolean and error code as in err table. function login_apop(socket, user, pw, challenge) if type(challenge) ~= "string" then return false, err.informationMissing end @@ -135,9 +135,9 @@ end --- -- Asks POP3 server for capabilities ---@param host Host to be queried ---@param port Port to connect to ---@return Table containing capabilities +--@param host Host to be queried. +--@param port Port to connect to. +--@return Table containing capabilities. function capabilities(host, port) local socket = nmap.new_socket() local capas = {} @@ -178,11 +178,11 @@ function capabilities(host, port) end --- --- Try to login using AUTH command using SASL/CRAM-MD5 method ---@param socket Socket connected to POP3 server ---@param user User string ---@param pw Password string ---@return Success as boolean and error code as in err table +-- Try to login using AUTH command using SASL/CRAM-MD5 method. +--@param socket Socket connected to POP3 server. +--@param user User string. +--@param pw Password string. +--@return Success as boolean and error code as in err table. function login_sasl_crammd5(socket, user, pw) socket:send("AUTH CRAM-MD5\r\n") @@ -204,7 +204,7 @@ function login_sasl_crammd5(socket, user, pw) end end ---- overwrite functions requiring OpenSSL if we got no OpenSSL +-- Overwrite functions requiring OpenSSL if we got no OpenSSL. if not HAVE_SSL then local no_ssl = function() diff --git a/nselib/shortport.lua b/nselib/shortport.lua index 83ae6eb13..56cb0ce50 100644 --- a/nselib/shortport.lua +++ b/nselib/shortport.lua @@ -1,18 +1,18 @@ ---- Functions for common port tests.\n\n --- Takes a number as its argument and returns that many bytes. --- It can be used to get a buffered version of sockobj:receive_bytes(n) in --- case a script requires more than one fixed-size chunk, as the unbuffered --- version may return more bytes than requested and thus would require you --- to do the parsing on your own. +--- Functions for building short portrules. +-- \n\n +-- Since portrules are mostly the same for many scripts, this +-- module provides functions for the most common tests. --@copyright See nmaps COPYING for licence module(... or "shortport", package.seeall) ---- The port argument is either a number or a table of numbers which are --- interpreted as port numbers, against which the script should run. See --- module description for other arguments. --- @param port The port or list of ports to run against +--- Return a portrule that returns true when given an open port matching a +-- single port number or a list of port numbers. +-- @param port A single port number or a list of port numbers. +-- @param _proto The protocol to match against, default "tcp". +-- @param _state A state or list of states to match against, default {"open", "open|filtered"}. -- @return Function for the portrule. +-- @usage portrule = shortport.portnumber({80, 443}) portnumber = function(port, _proto, _state) local port_table, state_table local proto = _proto or "tcp" @@ -45,14 +45,19 @@ portnumber = function(port, _proto, _state) end end ---- The service argument is either a string or a table of strings which are --- interpreted as service names (e.g. "http", "https", "smtp" or "ftp") --- against which the script should run. These service names are determined --- by Nmap's version scan or (if no version scan information is available) --- the service assigned to the port in nmap-services (e.g. "http" for TCP --- port 80). +--- Return a portrule that returns true when given an open port with a +--service name matching a single service name or a list of service +--names. +-- \n\n +-- A service name is something like "http", "https", "smtp", or "ftp". +-- These service names are determined by Nmap's version scan or (if no +-- version scan information is available) the service assigned to the +-- port in nmap-services (e.g. "http" for TCP port 80). -- @param service Service name or a list of names to run against. +-- @param _proto The protocol to match against, default "tcp". +-- @param _state A state or list of states to match against, default {"open", "open|filtered"}. -- @return Function for the portrule. +-- @usage portrule = shortport.service("ftp") service = function(service, _proto, _state) local service_table, state_table local state = _state or {"open", "open|filtered"} @@ -85,12 +90,19 @@ service = function(service, _proto, _state) end end ---- Run the script if either the port or service is available. This is --- a combination of shortport.portnumber and shortport.service, since --- many scripts explicitly try to run against the well-known ports, --- but want also to run against any other port which was discovered to --- run the named service. +--- Return a portrule that returns true when given an open port matching +-- either a port number or service name. +-- \n\n +-- This function is a combination of the portnumber and service +-- functions. The port and service may be single values or a list of +-- values as in those functions. Many scripts explicitly try to run +-- against the well-known ports, but want also to run against any other +-- port which was discovered to run the named service. -- @usage portrule = shortport.port_or_service(22,"ssh"). +-- @param _port A single port number or a list of port numbers. +-- @param _service Service name or a list of names to run against. +-- @param proto The protocol to match against, default "tcp". +-- @param _state A state or list of states to match against, default {"open", "open|filtered"}. -- @return Function for the portrule. port_or_service = function(_port, _service, proto, _state) local state = _state or {"open", "open|filtered"} diff --git a/nselib/smb.lua b/nselib/smb.lua index c14815420..cb011de57 100644 --- a/nselib/smb.lua +++ b/nselib/smb.lua @@ -1,4 +1,6 @@ ---- A library for SMB (Server Message Block) (aka CIFS) traffic. This traffic is normally +--- A library for SMB (Server Message Block) (aka CIFS) traffic. +-- \n\n +-- This traffic is normally -- sent to/from ports 139 or 445 of Windows systems, although it's also implemented by -- others (the most notable one being Samba). \n --\n diff --git a/nselib/snmp.lua b/nselib/snmp.lua index 1ccc6560b..c2d1a38cc 100644 --- a/nselib/snmp.lua +++ b/nselib/snmp.lua @@ -1,4 +1,4 @@ ---- SNMP functions +--- SNMP functions. --@copyright See nmaps COPYING for licence @@ -6,9 +6,9 @@ module(... or "snmp",package.seeall) --- --- Encodes an Integer according to ASN.1 basic encoding rules ---@param val Value to be encoded ---@return encoded integer +-- Encodes an Integer according to ASN.1 basic encoding rules. +--@param val Value to be encoded. +--@return encoded integer. local function encodeInt(val) local lsb = 0 if val > 0 then @@ -44,9 +44,9 @@ end --- --- Encodes the length part of a ASN.1 encoding triplet ---@param val Value to be encoded ---@return encoded length value +-- Encodes the length part of a ASN.1 encoding triplet. +--@param val Value to be encoded. +--@return encoded length value. local function encodeLength(val) if (val >= 128) then local valStr = "" @@ -65,9 +65,9 @@ end --- -- Encodes a given value according to ASN.1 basic encoding --- rules for SNMP packet creation ---@param val Value to be encoded ---@return encoded value +-- rules for SNMP packet creation. +--@param val Value to be encoded. +--@return encoded value. function encode(val) local vtype = type(val) if (vtype == 'number') then @@ -119,10 +119,10 @@ end --- -- Decodes length part of encoded value according to --- ASN.1 basic encoding rules ---@param encStr Encoded string ---@param pos Current position in the string ---@return The position after decoding and the length of the following value +-- ASN.1 basic encoding rules. +--@param encStr Encoded string. +--@param pos Current position in the string. +--@return The position after decoding and the length of the following value. local function decodeLength(encStr, pos) local elen pos, elen = bin.unpack('C', encStr, pos) @@ -143,11 +143,11 @@ end --- -- Decodes an Integer according to ASN.1 basic --- encoding rules ---@param encStr Encoded string ---@param len Length of integer in bytes ---@param pos Current position in the string ---@return The position after decoding and the decoded integer +-- encoding rules. +--@param encStr Encoded string. +--@param len Length of integer in bytes. +--@param pos Current position in the string. +--@return The position after decoding and the decoded integer. local function decodeInt(encStr, len, pos) local hexStr pos, hexStr = bin.unpack("H" .. len, encStr, pos) @@ -160,11 +160,11 @@ end --- -- Decodes a sequence according to ASN.1 basic --- encoding rules ---@param encStr Encoded string ---@param len Length of sequence in bytes ---@param pos Current position in the string ---@return The position after decoding and the decoded sequence as a table +-- encoding rules. +--@param encStr Encoded string. +--@param len Length of sequence in bytes. +--@param pos Current position in the string. +--@return The position after decoding and the decoded sequence as a table. local function decodeSeq(encStr, len, pos) local seq = {} local sPos = 1 @@ -181,10 +181,10 @@ end --- -- Decodes an SNMP packet or a part of it according --- to ASN.1 basic encoding rules ---@param encStr Encoded string ---@param pos Current position in the string ---@return The position after decoding and the decoded value(s) +-- to ASN.1 basic encoding rules. +--@param encStr Encoded string. +--@param pos Current position in the string. +--@return The position after decoding and the decoded value(s). function decode(encStr, pos) local etype, elen pos, etype = bin.unpack("H1", encStr, pos) @@ -273,10 +273,10 @@ end --- -- Decodes an SNMP packet or a part of it according --- to ASN.1 basic encoding rules ---@param encStr Encoded string ---@param pos Current position in the string ---@return The decoded value(s) +-- to ASN.1 basic encoding rules. +--@param encStr Encoded string. +--@param pos Current position in the string. +--@return The decoded value(s). function dec(encStr, pos) local result local _ @@ -285,10 +285,10 @@ function dec(encStr, pos) end --- --- Create SNMP packet ---@param PDU SNMP Protocol Data Unit to be encapsulated in the packet ---@param version SNMP version, default 0 (SNMP V1) ---@param commStr community string, if not already supplied in registry or as script argument +-- Create SNMP packet. +--@param PDU SNMP Protocol Data Unit to be encapsulated in the packet. +--@param version SNMP version, default 0 (SNMP V1). +--@param commStr community string, if not already supplied in registry or as script argument. function buildPacket(PDU, version, commStr) local comm = nmap.registry.args.snmpcommunity if (not comm) then comm = nmap.registry.snmpcommunity end @@ -305,10 +305,13 @@ end --- --- Create SNMP Get Request PDU ---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx) ---@param OIDs Object identifiers to be queried ---@return Table representing PDU +-- Create SNMP Get Request PDU. +--@param options A table containing the following keys and values:\n +--"reqId": request ID\n +--"err": error\n +--"errIdx": error index +--@param ... Object identifiers to be queried. +--@return Table representing PDU. function buildGetRequest(options, ...) if not options then options = {} end @@ -337,10 +340,13 @@ end --- --- Create SNMP Get Next Request PDU ---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx) ---@param OIDs Object identifiers to be queried ---@return Table representing PDU +-- Create SNMP Get Next Request PDU. +--@param options A table containing the following keys and values:\n +--"reqId": request ID\n +--"err": error\n +--"errIdx": error index +--@param ... Object identifiers to be queried. +--@return Table representing PDU. function buildGetNextRequest(options, ...) if not options then options = {} end @@ -368,12 +374,16 @@ function buildGetNextRequest(options, ...) end --- --- Create SNMP Set Request PDU --- Takes one OID/value pair or an already prepared table ---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx) ---@param OIDs Object identifiers of object to be set ---@param value To which value object should be set. If given a table, use table instead of OID/value pair ---@return Table representing PDU +-- Create SNMP Set Request PDU. +-- \n\n +-- Takes one OID/value pair or an already prepared table. +--@param options A table containing the following keys and values:\n +--"reqId": request ID\n +--"err": error\n +--"errIdx": error index +--@param oid Object identifiers of object to be set. +--@param value To which value object should be set. If given a table, use table instead of OID/value pair. +--@return Table representing PDU. function buildSetRequest(options, oid, value) if not options then options = {} end @@ -437,12 +447,16 @@ function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp) end --- --- Create SNMP Get Response PDU --- Takes one OID/value pair or an already prepared table ---@param options Configure PDU: request ID (reqId), error and error index (err, errIdx) ---@param OIDs Object identifiers of object to be sent back ---@param value To which value object or returned object. If given a table, use table instead of OID/value pair ---@return Table representing PDU +-- Create SNMP Get Response PDU. +-- \n\n +-- Takes one OID/value pair or an already prepared table. +--@param options A table containing the following keys and values:\n +--"reqId": request ID\n +--"err": error\n +--"errIdx": error index +--@param oid Object identifiers of object to be sent back. +--@param value To which value object or returned object. If given a table, use table instead of OID/value pair. +--@return Table representing PDU. function buildGetResponse(options, oid, value) if not options then options = {} end @@ -475,9 +489,9 @@ function buildGetResponse(options, oid, value) end --- --- Transforms a string into an object identifier table ---@param oidStr Object identifier as string, for example "1.3.6.1.2.1.1.1.0" ---@return Table representing OID +-- Transforms a string into an object identifier table. +--@param oidStr Object identifier as string, for example "1.3.6.1.2.1.1.1.0". +--@return Table representing OID. function str2oid(oidStr) local oid = {} for n in string.gmatch(oidStr, "%d+") do @@ -488,18 +502,18 @@ function str2oid(oidStr) end --- --- Transforms a table representing an object identifier to a string ---@param oid Object identifier table ---@return OID string +-- Transforms a table representing an object identifier to a string. +--@param oid Object identifier table. +--@return OID string. function oid2str(oid) if (type(oid) ~= "table") then return 'invalid oid' end return table.concat(oid, '.') end --- --- Transforms a table representing an IP to a string ---@param ip IP table ---@return IP string +-- Transforms a table representing an IP to a string. +--@param ip IP table. +--@return IP string. function ip2str(ip) if (type(ip) ~= "table") then return 'invalid ip' end return table.concat(ip, '.') @@ -507,9 +521,9 @@ end --- --- Transforms a string into an IP table ---@param ipStr IP as string ---@return Table representing IP +-- Transforms a string into an IP table. +--@param ipStr IP as string. +--@return Table representing IP. function str2ip(ipStr) local ip = {} for n in string.gmatch(ipStr, "%d+") do @@ -521,9 +535,9 @@ end --- --- Fetches values from a SNMP response ---@param resp SNMP Response (will be decoded if necessary) ---@result Table with all decoded responses and their OIDs +-- Fetches values from a SNMP response. +--@param resp SNMP Response (will be decoded if necessary). +--@result Table with all decoded responses and their OIDs. function fetchResponseValues(resp) if (type(resp) == "string") then local _ @@ -568,8 +582,8 @@ end --- -- Fetches first value from a SNMP response. ---@param response SNMP Response (will be decoded if necessary) ---@return First decoded value of the response +--@param response SNMP Response (will be decoded if necessary). +--@return First decoded value of the response. function fetchFirst(response) local result = fetchResponseValues(response) if type(result) == "table" and result[1] and result[1][1] then return result[1][1] diff --git a/nselib/ssh1.lua b/nselib/ssh1.lua index 9cbbd9182..e5cc87a70 100644 --- a/nselib/ssh1.lua +++ b/nselib/ssh1.lua @@ -1,5 +1,7 @@ - --- @author = Sven Klemm +--- Functions for the SSH-1 protocol. +-- \n\n +-- This module also contains functions for formatting key fingerprints. +-- @author Sven Klemm -- @copyright See nmaps COPYING for licence module(... or "ssh1",package.seeall) @@ -10,9 +12,11 @@ local math = require "math" local stdnse = require "stdnse" local openssl = require "openssl" ---- fetch SSH1 host key ---@param host nmap host table ---@param port nmap port table +--- Fetch a SSH-1 host key. +--@param host Nmap host table. +--@param port Nmap port table. +--@return A table with the following keys: "exp", "mod", "bits", "key_type", +--"fp_input", "full_key", "algorithm", and "fingerprint". fetch_host_key = function(host, port) local socket = nmap.new_socket() local catch = function() socket:close() end @@ -61,13 +65,13 @@ fetch_host_key = function(host, port) end end ---- format key as hexadecimal fingerprint +--- Format a key fingerprint in hexadecimal. fingerprint_hex = function( fingerprint, algorithm, bits ) fingerprint = stdnse.tohex(fingerprint,{separator=":",group=2}) return ("%d %s (%s)"):format( bits, fingerprint, algorithm ) end ---- format key as bubblebabble fingerprint +--- Format a key fingerprint in Bubble Babble. fingerprint_bubblebabble = function( fingerprint, algorithm, bits ) local vowels = {'a','e','i','o','u','y'} local consonants = {'b','c','d','f','g','h','k','l','m','n','p','r','s','t','v','z','x'} @@ -100,8 +104,9 @@ fingerprint_bubblebabble = function( fingerprint, algorithm, bits ) return ("%d %s (%s)"):format( bits, s, algorithm ) end ---- format key as visual fingerprint --- ported from http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/src/usr.bin/ssh/key.c +--- Format a key fingerprint into a visual ASCII art representation. +-- \n\n +-- Ported from http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/src/usr.bin/ssh/key.c. fingerprint_visual = function( fingerprint, algorithm, bits ) local i,j,field,characters,input,fieldsize_x,fieldsize_y,s fieldsize_x, fieldsize_y = 17, 9 diff --git a/nselib/ssh2.lua b/nselib/ssh2.lua index 7c54c11c2..1eb57470e 100644 --- a/nselib/ssh2.lua +++ b/nselib/ssh2.lua @@ -1,5 +1,5 @@ - --- @author = Sven Klemm +--- Functions for the SSH-2 protocol. +-- @author Sven Klemm -- @copyright See nmaps COPYING for licence module(... or "ssh2",package.seeall) @@ -12,12 +12,12 @@ require "stdnse" -- table holding transport layer functions transport = {} --- table of SSH2 constants +-- table of SSH-2 constants local SSH2 ---- pack multiprecision integer for sending ---@param bn openssl bignum ---@return packed multiprecision integer +--- Pack a multiprecision integer for sending. +--@param bn openssl bignum. +--@return packed multiprecision integer. transport.pack_mpint = function( bn ) local bytes, packed bytes = bn:num_bytes() @@ -29,9 +29,9 @@ transport.pack_mpint = function( bn ) return bin.pack( ">IA", bytes, packed ) end ---- build a ssh2 packet ---@param payload payload of the packet ---@return packet to send on the wire +--- Build an SSH-2 packet. +--@param payload payload of the packet. +--@return packet to send on the wire. transport.build = function( payload ) local packet_length, padding_length padding_length = 8 - ( (payload:len() + 1 + 4 ) % 8 ) @@ -39,9 +39,9 @@ transport.build = function( payload ) return bin.pack( ">IcAA", packet_length, padding_length, payload, openssl.rand_pseudo_bytes( padding_length ) ) end ---- extract the payload from a received SSH2 packet ---@param received SSH2 packet ---@return payload of the SSH2 packet +--- Extract the payload from a received SSH-2 packet. +--@param received SSH2 packet. +--@return payload of the SSH2 packet. transport.payload = function( packet ) local packet_length, padding_length, payload_length, payload, offset offset, packet_length, padding_length = bin.unpack( ">Ic", packet ) @@ -50,12 +50,12 @@ transport.payload = function( packet ) return payload end ---- build kexdh_init packet +--- Build kexdh_init packet. transport.kexdh_init = function( e ) return bin.pack( ">cA", SSH2.SSH_MSG_KEXDH_INIT, transport.pack_mpint( e ) ) end ---- build kex_init packet +--- Build kex_init packet. transport.kex_init = function( cookie, options ) options = options or {} kex_algorithms = "diffie-hellman-group1-sha1" @@ -75,8 +75,9 @@ transport.kex_init = function( cookie, options ) return payload end ---- parse kexinit package --- returns an empty table in case of an error +--- Parse kexinit package. +-- \n\n +-- Returns an empty table in case of an error transport.parse_kex_init = function( payload ) local _, offset, msg_code, parsed, fields, fieldname parsed = {} @@ -100,11 +101,11 @@ transport.parse_kex_init = function( payload ) end ---- fetch SSH2 host key ---@param host nmap host table ---@param port nmap port table ---@param key_type key type to fetch ---@return table containing the key and fingerprint +--- Fetch an SSH-2 host key. +--@param host Nmap host table. +--@param port Nmap port table. +--@param key_type key type to fetch. +--@return table containing the key and fingerprint. fetch_host_key = function( host, port, key_type ) local socket = nmap.new_socket() local catch = function() socket:close() end diff --git a/nselib/stdnse.lua b/nselib/stdnse.lua index df8bd6426..3c5f20525 100644 --- a/nselib/stdnse.lua +++ b/nselib/stdnse.lua @@ -1,4 +1,6 @@ ---- Standard Nmap Engine functions. +--- Standard Nmap Scripting Engine functions. +-- \n\n +-- This module contains various handy functions which are too small to justify modules of their own. --@copyright See nmaps COPYING for licence local assert = assert; @@ -14,9 +16,14 @@ local EMPTY = {}; -- Empty constant table module(... or "stdnse"); ---- Prints debug information according with verbosity level --- formatted using Lua's standard string.format function. ---@param level Optional argument for verbosity. +--- Prints a formatted debug message if the current verbosity level is greater +-- than or equal to a given level. +-- \n\n +-- This is a convenience wrapper around nmap.print_debug_unformatted. The first +-- optional numeric argument, verbosity, is used as the necessary debug level +-- to print the message (it defaults to 1 if omitted). All remaining arguments +-- are processed with Lua's string.format() function. +--@param level Optional verbosity level. --@param fmt Format string according to string.format specifiers. --@param ... Arguments to format. --@see string.format @@ -29,10 +36,13 @@ print_debug = function(level, fmt, ...) end end ---- Concat the contents of the parameter list. Each string is --- separated by the string delimiter (just like in perl). +--- Join a list of string with a separator string. +-- \n\n -- Example: strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"}) -- --> "Anna, Bob, Charlie, Dolores" +-- \n\n +-- Basically this is Lua's table.concat() function with the parameters swapped +-- for coherence. --@param delimiter String to delimit each element of the list. --@param list Array of strings to concatenate. --@return Concatenated string. @@ -40,12 +50,11 @@ function strjoin(delimiter, list) return concat(list, delimiter); end ---- Split text into a list consisting of the strings in text, --- separated by strings matching delimiter (which may be a pattern). --- example: strsplit(",%s*", "Anna, Bob, Charlie, Dolores") +--- Split a string at a given delimiter, which may be a pattern. +-- Example: strsplit(",%s*", "Anna, Bob, Charlie, Dolores") --@param delimiter String which delimits the split strings. --@param text String to split. ---@return List of strings. +--@return List of substrings without the delimiter. function strsplit(delimiter, text) local list, pos = {}, 1; @@ -64,7 +73,10 @@ function strsplit(delimiter, text) return list; end ---- This function operates on a socket attempting to read data. It separates +--- Return a wrapper closure around a socket that buffers socket reads into +-- chunks separated by a pattern. +-- \n\n +-- This function operates on a socket attempting to read data. It separates -- the data by sep and, for each invocation, returns a piece of the -- separated data. Typically this is used to iterate over the lines of -- data received from a socket (sep = "\r?\n"). The returned string does @@ -132,7 +144,8 @@ do f = "1111" }; ---- Converts the given number, n, to a string in a binary number format. +--- Converts the given number, n, to a string in a binary number format (10 +-- becomes "1010"). --@param n Number to convert. --@return String in binary format. function tobinary(n) @@ -141,7 +154,8 @@ do end end ---- Converts the given number, n, to a string in an octal number format. +--- Converts the given number, n, to a string in an octal number format (10 +-- becomes "12"). --@param n Number to convert. --@return String in octal format. function tooctal(n) @@ -149,16 +163,22 @@ function tooctal(n) return ("%o"):format(n) end ---- encode string or number to hexadecimal --- example: stdnse.tohex("abc") => "616263" --- stdnse.tohex("abc",{separator=":"}) => "61:62:63" --- stdnse.tohex("abc",{separator=":",group=4}) => "61:6263" --- stdnse.tohex(123456) => "1e240" --- stdnse.tohex(123456,{separator=":"}) => "1:e2:40" --- stdnse.tohex(123456,{separator=":",group=4}) => "1:e240" ---@param s string or number to be encoded ---@param options table specifiying formatting options ---@return hexadecimal encoded string +--- Encode a string or number in hexadecimal (10 becomes "a", "A" becomes +-- "41"). +-- \n\n +-- The returned string may be chunked into groups of a given size, separated +-- by a given string. +-- \n\n +-- Examples:\n +-- stdnse.tohex("abc") => "616263"\n +-- stdnse.tohex("abc",{separator=":"}) => "61:62:63"\n +-- stdnse.tohex("abc",{separator=":",group=4}) => "61:6263"\n +-- stdnse.tohex(123456) => "1e240"\n +-- stdnse.tohex(123456,{separator=":"}) => "1:e2:40"\n +-- stdnse.tohex(123456,{separator=":",group=4}) => "1:e240"\n +--@param s string or number to be encoded. +--@param options table specifiying formatting options. +--@return hexadecimal encoded string. function tohex( s, options ) options = options or EMPTY local separator = options.separator diff --git a/nselib/strbuf.lua b/nselib/strbuf.lua index e1c8e6317..5afa2d093 100644 --- a/nselib/strbuf.lua +++ b/nselib/strbuf.lua @@ -1,4 +1,38 @@ ---- String Buffer Facilities +--- String Buffer facilities. +-- \n\n +-- Lua's string operations are very flexible and offer an easy-to-use way to +-- manipulate strings. Concatenation using the .. operator is such an +-- operation. The drawback of the built-in API however is the way it handles +-- concatenation of many string values. Since strings in Lua are immutable +-- values, each time you concatenate two strings both get copied into the result +-- string. +-- \n\n +-- The strbuf module offers a workaround for this problem, while +-- maintaining the nice syntax. This is accomplished by overloading the +-- concatenation operator (..) the equality operator (==) and the tostring +-- operator. By overloading these operators, we reduce the overhead of using a +-- string buffer instead of a plain string to wrap the first literal string +-- assigned to a variable inside a strbuf.new() call. Afterwards you can append +-- to the string buffer, or compare two string buffers for equality just as you +-- would do with normal strings. +-- \n\n +-- When looking at the details there are some more +-- restrictions/oddities: The concatenation operator requires its left-hand +-- value to be a string buffer. Therefore, if you want to prepend a string to a +-- given string buffer you have to create a new string buffer out of the string +-- you want to prepend. The string buffer's tostring operator concatenates the +-- strings inside the buffer using newlines by default, since this appears to be +-- the separator used most often. +-- \n\n +-- Example usage:\n +-- local buf = strbuf.new()\n +-- local buf2 = strbuf.new('hello')\n +-- buf = buf .. 'string'\n +-- buf = buf .. 'data'\n +-- print(buf) -- default separator is a new line\n +-- print(strbuf.dump(buf)) -- no separator\n +-- print(strbuf.dump(buf, ' ')) -- separated by spaces\n +-- strbuf.clear(buf) --@copyright See nmaps COPYING for license -- DEPENDENCIES -- @@ -19,23 +53,10 @@ module(... or "strbuf"); -- operations are needed a string buffer should be used instead -- e.g. for i = 1, 10 do s = s..i end ---[[ - local buf = strbuf.new() - -- from here buf may be used like a string for concatenation operations - -- (the lefthand-operand has to be a strbuf, the righthand-operand may be - -- a string or a strbuf) - -- alternativly you can assign a value (which will become the first string - -- inside the buffer) with new - local buf2 = strbuf.new('hello') - buf = buf .. 'string' - buf = buf .. 'data' - print(buf) -- default seperator is a new line - print(strbuf.dump(buf)) -- no seperator - print(strbuf.dump(buf, ' ')) -- seperated by spaces - strbuf.clear(buf) ---]] - --- Dumps the string buffer as a string. +-- \n\n +-- The second parameter is used as a delimiter between the strings stored inside +-- strbuf. --@name dump --@class function --@param sbuf String buffer to dump. @@ -102,10 +123,11 @@ local mt = { __index = _M, }; ---- Create a new string buffer. The equals and tostring operators for String +--- Create a new string buffer. +-- \n\n +-- The optional arguments are added to the string buffer. The result of adding +-- non-strings is undefined. The equals and tostring operators for string -- buffers are overloaded to be strbuf.eqbuf and strbuf.tostring respectively. --- All functions in strbuf can be accessed by a String buffer using the self --- calling mechanism in Lua (e.g. strbuf:dump(...)). --@param ... Strings to add to the buffer initially. --@return String buffer. function new(...)