diff --git a/nselib/pop3.lua b/nselib/pop3.lua index 7adc212ec..5eaf5d1d0 100644 --- a/nselib/pop3.lua +++ b/nselib/pop3.lua @@ -24,9 +24,9 @@ err = { } --- --- Check a POP3 response for "+OK". ---@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 The string "+OK" if found or nil otherwise. function stat(line) return string.match(line, "+OK") end @@ -34,11 +34,12 @@ end --- --- 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. +-- Try to log in using the USER/PASS commands. +-- @param socket Socket connected to POP3 server. +-- @param user User string. +-- @param pw Password string. +-- @return Status (true or false). +-- @return Error code if status is false. function login_user(socket, user, pw) socket:send("USER " .. user .. "\r\n") status, line = socket:receive_lines(1) @@ -54,11 +55,12 @@ 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 the the AUTH command using SASL/Plain method. +-- @param socket Socket connected to POP3 server. +-- @param user User string. +-- @param pw Password string. +-- @return Status (true or false). +-- @return Error code if status is false. function login_sasl_plain(socket, user, pw) local auth64 = base64.enc(user .. "\0" .. user .. "\0" .. pw) @@ -74,11 +76,12 @@ 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 the AUTH command using SASL/Login method. +-- @param user User string. +-- @param pw Password string. +-- @param pw String containing password to login. +-- @return Status (true or false). +-- @return Error code if status is false. function login_sasl_login(socket, user, pw) local user64 = base64.enc(user) @@ -112,12 +115,13 @@ 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 the 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 Status (true or false). +-- @return Error code if status is false. function login_apop(socket, user, pw, challenge) if type(challenge) ~= "string" then return false, err.informationMissing end @@ -134,10 +138,10 @@ function login_apop(socket, user, pw, challenge) end --- --- Asks POP3 server for capabilities ---@param host Host to be queried. ---@param port Port to connect to. ---@return Table containing capabilities. +-- Asks a POP3 server for 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 +182,12 @@ 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 the AUTH command using SASL/CRAM-MD5 method. +-- @param socket Socket connected to POP3 server. +-- @param user User string. +-- @param pw Password string. +-- @return Status (true or false). +-- @return Error code if status is false. function login_sasl_crammd5(socket, user, pw) socket:send("AUTH CRAM-MD5\r\n") diff --git a/nselib/shortport.lua b/nselib/shortport.lua index 841ec58f1..7fc28eddd 100644 --- a/nselib/shortport.lua +++ b/nselib/shortport.lua @@ -1,5 +1,5 @@ --- 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 Same as Nmap--See http://nmap.org/book/man-legal.html @@ -9,8 +9,9 @@ module(... or "shortport", package.seeall) --- 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"}. +-- @param _proto The protocol to match against, default "tcp". +-- @param _state A state or table 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) @@ -46,16 +47,18 @@ portnumber = function(port, _proto, _state) end --- 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). +-- service name matching a single service name or a list of service +-- names. +-- +-- 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"}. +-- @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) @@ -92,17 +95,18 @@ end --- 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. +-- +-- 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. This function exists because 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"}. +-- @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/snmp.lua b/nselib/snmp.lua index dc8a644a6..96840068c 100644 --- a/nselib/snmp.lua +++ b/nselib/snmp.lua @@ -7,8 +7,8 @@ module(... or "snmp",package.seeall) --- -- Encodes an Integer according to ASN.1 basic encoding rules. ---@param val Value to be encoded. ---@return encoded integer. +-- @param val Value to be encoded. +-- @return Encoded integer. local function encodeInt(val) local lsb = 0 if val > 0 then @@ -45,8 +45,8 @@ end --- -- Encodes the length part of a ASN.1 encoding triplet. ---@param val Value to be encoded. ---@return encoded length value. +-- @param val Value to be encoded. +-- @return Encoded length value. local function encodeLength(val) if (val >= 128) then local valStr = "" @@ -64,10 +64,10 @@ 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. +-- Encodes a given value according to ASN.1 basic encoding 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 @@ -118,11 +118,12 @@ 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. +-- 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. +-- @return The length of the following value. local function decodeLength(encStr, pos) local elen pos, elen = bin.unpack('C', encStr, pos) @@ -142,12 +143,12 @@ 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. +-- 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. +-- @return The decoded integer. local function decodeInt(encStr, len, pos) local hexStr pos, hexStr = bin.unpack("H" .. len, encStr, pos) @@ -159,12 +160,12 @@ local function decodeInt(encStr, len, pos) 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. +-- 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. +-- @return The decoded sequence as a table. local function decodeSeq(encStr, len, pos) local seq = {} local sPos = 1 @@ -180,11 +181,12 @@ local function decodeSeq(encStr, len, pos) 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). +-- 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 +-- @return The decoded value(s). function decode(encStr, pos) local etype, elen pos, etype = bin.unpack("H1", encStr, pos) @@ -272,11 +274,11 @@ function decode(encStr, pos) 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). +-- 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). function dec(encStr, pos) local result local _ @@ -285,10 +287,11 @@ 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 an 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,13 +308,13 @@ end --- --- 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. +-- Create an SNMP Get Request PDU. +-- @param options A table containing the following fields: +-- * "reqId": Request ID. +-- * "err": Error. +-- * "errIdx": Error index. +-- @param ... Object identifiers to be queried. +-- @return Table representing PDU. function buildGetRequest(options, ...) if not options then options = {} end @@ -340,13 +343,13 @@ end --- --- 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. +-- Create an SNMP Get Next Request PDU. +-- @param options A table containing the following fields: +-- * "reqId": Request ID. +-- * "err": Error. +-- * "errIdx": Error index. +-- @param ... Object identifiers to be queried. +-- @return Table representing PDU. function buildGetNextRequest(options, ...) if not options then options = {} end @@ -374,16 +377,17 @@ function buildGetNextRequest(options, ...) end --- --- Create SNMP Set Request PDU. --- \n\n +-- Create an SNMP Set Request PDU. +-- -- 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. +-- @param options A table containing the following keys and values: +-- * "reqId": Request ID. +-- * "err": Error. +-- * "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 the +-- table instead of OID/value pair. +-- @return Table representing PDU. function buildSetRequest(options, oid, value) if not options then options = {} end @@ -414,8 +418,8 @@ function buildSetRequest(options, oid, value) end --- --- Create SNMP Trap PDU ---@return Table representing PDU +-- Create an SNMP Trap PDU. +-- @return Table representing PDU function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp) local req = {} req._snmp = 'A4' @@ -442,16 +446,16 @@ function buildTrap(enterpriseOid, agentIp, genTrap, specTrap, timeStamp) end --- --- Create SNMP Get Response PDU. --- \n\n +-- Create an SNMP Get Response PDU. +-- -- 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. +-- @param options A table containing the following keys and values: +-- * "reqId": Request ID. +-- * "err": Error. +-- * "errIdx": Error index. +-- @param oid Object identifiers of object to be sent back. +-- @param value If given a table, use the table instead of OID/value pair. +-- @return Table representing PDU. function buildGetResponse(options, oid, value) if not options then options = {} end @@ -485,8 +489,9 @@ 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. +-- @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 @@ -498,8 +503,8 @@ end --- -- Transforms a table representing an object identifier to a string. ---@param oid Object identifier table. ---@return OID 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, '.') @@ -507,8 +512,8 @@ end --- -- Transforms a table representing an IP to a string. ---@param ip IP table. ---@return IP string. +-- @param ip IP table. +-- @return IP string. function ip2str(ip) if (type(ip) ~= "table") then return 'invalid ip' end return table.concat(ip, '.') @@ -517,8 +522,8 @@ end --- -- Transforms a string into an IP table. ---@param ipStr IP as string. ---@return Table representing IP. +-- @param ipStr IP as string. +-- @return Table representing IP. function str2ip(ipStr) local ip = {} for n in string.gmatch(ipStr, "%d+") do @@ -531,8 +536,8 @@ end --- -- Fetches values from a SNMP response. ---@param resp SNMP Response (will be decoded if necessary). ---@return Table with all decoded responses and their OIDs. +-- @param resp SNMP Response (will be decoded if necessary). +-- @return Table with all decoded responses and their OIDs. function fetchResponseValues(resp) if (type(resp) == "string") then local _ @@ -576,9 +581,9 @@ end --- --- Fetches first value from a SNMP response. ---@param response SNMP Response (will be decoded if necessary). ---@return First decoded value of the response. +-- Fetches the first value from a SNMP 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 76f3f7256..6fd0f1ae8 100644 --- a/nselib/ssh1.lua +++ b/nselib/ssh1.lua @@ -1,5 +1,5 @@ --- Functions for the SSH-1 protocol. --- \n\n +-- -- This module also contains functions for formatting key fingerprints. -- @author Sven Klemm -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html @@ -12,11 +12,13 @@ local math = require "math" local stdnse = require "stdnse" local openssl = require "openssl" ---- 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 an SSH-1 host key. +-- @param host Nmap host table. +-- @param port Nmap port table. +-- @return A table with the following fields: exp, +-- mod, bits, key_type, +-- fp_input, full_key, algorithm, and +-- fingerprint. fetch_host_key = function(host, port) local socket = nmap.new_socket() local status @@ -70,12 +72,18 @@ fetch_host_key = function(host, port) end --- Format a key fingerprint in hexadecimal. +-- @param fingerprint Key fingerprint. +-- @param algorithm Key algorithm. +-- @param bits Key size in bits. fingerprint_hex = function( fingerprint, algorithm, bits ) fingerprint = stdnse.tohex(fingerprint,{separator=":",group=2}) return ("%d %s (%s)"):format( bits, fingerprint, algorithm ) end --- Format a key fingerprint in Bubble Babble. +-- @param fingerprint Key fingerprint. +-- @param algorithm Key algorithm. +-- @param bits Key size in bits. 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'} @@ -109,8 +117,11 @@ fingerprint_bubblebabble = function( fingerprint, algorithm, bits ) end --- 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. +-- @param fingerprint Key fingerprint. +-- @param algorithm Key algorithm. +-- @param bits Key size in bits. 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 9a49a286c..42f2af2b7 100644 --- a/nselib/ssh2.lua +++ b/nselib/ssh2.lua @@ -16,8 +16,8 @@ transport = {} local SSH2 --- Pack a multiprecision integer for sending. ---@param bn openssl bignum. ---@return packed multiprecision integer. +-- @param bn openssl bignum. +-- @return Packed multiprecision integer. transport.pack_mpint = function( bn ) local bytes, packed bytes = bn:num_bytes() @@ -30,8 +30,8 @@ transport.pack_mpint = function( bn ) end --- Build an SSH-2 packet. ---@param payload payload of the packet. ---@return packet to send on the wire. +-- @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 ) @@ -40,8 +40,8 @@ transport.build = function( payload ) end --- Extract the payload from a received SSH-2 packet. ---@param packet received SSH2 packet. ---@return payload of the SSH2 packet. +-- @param packet Peceived SSH-2 packet. +-- @return Payload of the SSH-2 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 a 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 a kex_init packet. transport.kex_init = function( cookie, options ) options = options or {} kex_algorithms = "diffie-hellman-group1-sha1" @@ -75,8 +75,8 @@ transport.kex_init = function( cookie, options ) return payload end ---- Parse kexinit package. --- \n\n +--- Parse a kexinit package. +-- -- Returns an empty table in case of an error transport.parse_kex_init = function( payload ) local _, offset, msg_code, parsed, fields, fieldname @@ -102,10 +102,12 @@ end --- 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. +-- @param host Nmap host table. +-- @param port Nmap port table. +-- @param key_type key type to fetch. +-- @return A table with the following fields: key, +-- key_type, fp_input, bits, +-- full_key, algorithm, and fingerprint. fetch_host_key = function( host, port, key_type ) local socket = nmap.new_socket() local status diff --git a/nselib/strbuf.lua b/nselib/strbuf.lua index 801fe0cac..ebf29b8df 100644 --- a/nselib/strbuf.lua +++ b/nselib/strbuf.lua @@ -1,38 +1,39 @@ ---- String Buffer facilities. --- \n\n +--- String buffer facilities. +-- -- 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 +-- 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 +-- values, each time you concatenate two strings both get copied into the +-- result string. +-- +-- 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 +-- concatenation operator (..), the equality operator (==) and the tostring +-- operator. A string buffer is created by passing a string to +-- strbuf.new(). Afterwards you can append to the string buffer, +-- or compare two string buffers for equality just as you would do with normal +-- strings. +-- +-- 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. +-- +-- Example usage: +-- +-- local buf = strbuf.new() +-- local buf2 = strbuf.new('hello') +-- buf = buf .. 'string' +-- buf = buf .. 'data' +-- print(buf) -- default separator is a newline +-- print(strbuf.dump(buf)) -- no separator +-- print(strbuf.dump(buf, ' ')) -- separated by spaces -- strbuf.clear(buf) +-- -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html -- DEPENDENCIES -- @@ -54,19 +55,20 @@ module(... or "strbuf"); -- e.g. for i = 1, 10 do s = s..i end --- 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. ---@param delimiter String to separate the buffer's contents. ---@return Concatenated string result. +-- the string buffer. +-- @name dump +-- @class function +-- @param sbuf String buffer to dump. +-- @param delimiter String to separate the buffer's contents. +-- @return Concatenated string result. dump = concat; ---- Appends the string s to the buffer, sbuf. ---@param sbuf String buffer. ---@param s String to append. +--- Appends a string to a string buffer. +-- @param sbuf String buffer. +-- @param s String to append. +-- @return sbuf. function concatbuf(sbuf, s) if type(s) == "string" then sbuf[#sbuf+1] = s; @@ -80,11 +82,11 @@ function concatbuf(sbuf, s) return sbuf; end ---- Determines if the two buffers are equal. Two buffers are equal +--- Determines if the two string buffers are equal. Two buffers are equal -- if they are the same or if they have equivalent contents. ---@param sbuf1 String buffer one. ---@param sbuf2 String buffer two. ---@return boolean true if equal, false otherwise. +-- @param sbuf1 String buffer one. +-- @param sbuf2 String buffer two. +-- @return True if equal, false otherwise. function eqbuf(sbuf1, sbuf2) if getmetatable(sbuf1) ~= getmetatable(sbuf2) then error("one or more operands is not a string buffer", 2); @@ -100,18 +102,17 @@ function eqbuf(sbuf1, sbuf2) end end ---- Clears the string buffer. ---@param sbuf String buffer. +--- Clears a string buffer. +-- @param sbuf String buffer. function clear(sbuf) for k in pairs(sbuf) do sbuf[k] = nil; end end ---- Returns the result of the buffer as a string. The delimiter used --- is a newline. ---@param sbuf String buffer. ---@return String made from concatenating the buffer. +--- Returns the string buffer as a string. The delimiter used is a newline. +-- @param sbuf String buffer. +-- @return String made from concatenating the buffer. function tostring(sbuf) return concat(sbuf, "\n"); end @@ -124,12 +125,13 @@ local mt = { }; --- 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. ---@param ... Strings to add to the buffer initially. ---@return String buffer. +-- non-strings is undefined. The equals and tostring +-- operators for string buffers are overloaded to be eqbuf and +-- tostring respectively. +-- @param ... Strings to add to the buffer initially. +-- @return String buffer. function new(...) return setmetatable({...}, mt); end diff --git a/nselib/tab.lua b/nselib/tab.lua index a355a6dc1..1aa86546a 100644 --- a/nselib/tab.lua +++ b/nselib/tab.lua @@ -1,25 +1,28 @@ --- Arrange output into tables. --- \n\n +-- -- This module provides NSE scripts with a way to output structured tables --- similar to NmapOutputTable.cc. --- \n\n --- Example usage:\n --- local t = tab.new(2)\n --- tab.add(t, 1, 'A1')\n --- tab.add(t, 2, 'A2')\n --- tab.nextrow(t)\n --- tab.add(t, 1, 'BBBBBBBBB1')\n --- tab.add(t, 2, 'BBB2')\n +-- similar to what NmapOutputTable.cc provides. +-- +-- Example usage: +-- +-- local t = tab.new(2) +-- tab.add(t, 1, 'A1') +-- tab.add(t, 2, 'A2') +-- tab.nextrow(t) +-- tab.add(t, 1, 'BBBBBBBBB1') +-- tab.add(t, 2, 'BBB2') -- tab.dump(t) +-- -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html module(... or "tab",package.seeall) require('strbuf') ---- Create and return a new table with a number of columns equal to cols and +--- Create and return a new table with a given number of columns and -- the row counter set to 1. --- @param cols the number of columns the table will hold. +-- @param cols The number of columns the table will hold. +-- @return A new table. function new(cols) assert(cols > 0) local table ={} @@ -31,13 +34,12 @@ function new(cols) end --- Add a new string item to a table at a given column position. --- \n\n --- The item will be added to the current row. If nextrow hasn't been called yet --- that will be row 1. -- --- @param t the table. --- @param v the string to add. --- @param c the column position at which to add the item. +-- The item will be added to the current row. If nextrow hasn't +-- been called yet that will be row 1. +-- @param t The table. +-- @param v The string to add. +-- @param c The column position at which to add the item. function add(t, c, v) assert(t) assert(v) @@ -59,11 +61,11 @@ function add(t, c, v) end --- Add a complete row to the table and move on to the next row. --- \n\n --- Calls add for each argument starting with the second argument --- and after that calls nextrow. --- @param t the table. --- @param ... the elements to add to the row. +-- +-- Calls add for each argument starting with the second argument +-- and after that calls nextrow. +-- @param t The table. +-- @param ... The elements to add to the row. function addrow(t, ...) for i=1, arg['n'] do add( t, i, tostring(arg[i]) ) @@ -74,7 +76,7 @@ end --- Move on to the next row in the table. If this is not called -- then previous column values will be over-written by subsequent -- values. --- @param t the table. +-- @param t The table. function nextrow(t) assert(t) assert(t['rows']) @@ -82,10 +84,10 @@ function nextrow(t) end --- Return a formatted string representation of the table. --- \n\n +-- -- The number of spaces in a column is based on the largest element in the -- column with an additional two spaces for padding. --- @param t the table. +-- @param t The table. function dump(t) assert(t) assert(t['rows']) diff --git a/nselib/unpwdb.lua b/nselib/unpwdb.lua index 7a8bc48d0..74d5c158c 100644 --- a/nselib/unpwdb.lua +++ b/nselib/unpwdb.lua @@ -1,19 +1,20 @@ --- Username/password database library. --- \n\n --- The usernames and passwords functions return multiple values for use --- with exception handling via nmap.new_try(). --- The first value is the boolean success indicator, the second value is --- the closure. --- \n\n --- The closures can take a parameter of "reset" to rewind the list to the --- beginning. --- \n\n +-- +-- The usernames and passwords functions return +-- multiple values for use with exception handling via +-- nmap.new_try(). The first value is the Boolean success +-- indicator, the second value is the closure. +-- +-- The closures can take an argument of "reset" to rewind the list +-- to the beginning. +-- -- You can select your own username and/or password database to read from with --- the script arguments userdb and passdb, respectively. Comments are allowed --- in these files, prefixed with "#!comment:". Comments cannot be on the same --- line as a username or password because this leaves too much ambiguity, e.g. --- does the password in "mypass #!comment: blah" contain a space, two spaces, --- or do they just separate the password from the comment? +-- the script arguments userdb and passdb, +-- respectively. Comments are allowed in these files, prefixed with +-- "#!comment:". Comments cannot be on the same line as a +-- username or password because this leaves too much ambiguity, e.g. does the +-- password in "mypass #!comment: blah" contain a space, two +-- spaces, or do they just separate the password from the comment? -- -- @author Kris Katterjohn 06/2008 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html @@ -89,14 +90,15 @@ local closure = function(table) end end ---- Returns the suggested number of seconds to attempt a brute --- force attack, based on Nmap's timing values (-T4, etc) and whether or not a +--- Returns the suggested number of seconds to attempt a brute force attack, +-- based on Nmap's timing values (-T4 etc.) and whether or not a -- user-defined list is used. --- \n\n --- You can use the script argument "notimelimit" to make this function return --- nil, which means the brute-force should run until the list is empty. If --- "notimelimit" is not used, be sure to still check for nil return values on --- the above two functions in case you finish before the time limit is up. +-- +-- You can use the script argument notimelimit to make this +-- function return nil, which means the brute-force should run +-- until the list is empty. If notimelimit is not used, be sure to +-- still check for nil return values on the above two functions in +-- case you finish before the time limit is up. timelimit = function() -- If we're reading from a user-defined username or password list, -- we'll give them a timeout 1.5x the default. If the "notimelimit" @@ -118,7 +120,8 @@ timelimit = function() end --- Returns a function closure which returns a new username with every call --- until the username list is exhausted (in which case it returns nil). +-- until the username list is exhausted (in which case it returns +-- nil). -- @return boolean Status. -- @return function The usernames iterator. usernames = function() @@ -136,7 +139,8 @@ usernames = function() end --- Returns a function closure which returns a new password with every call --- until the password list is exhausted (in which case it returns nil). +-- until the password list is exhausted (in which case it returns +-- nil). -- @return boolean Status. -- @return function The passwords iterator. passwords = function() diff --git a/nselib/url.lua b/nselib/url.lua index 6a1dab920..938fa4307 100644 --- a/nselib/url.lua +++ b/nselib/url.lua @@ -40,9 +40,9 @@ local segment_set = make_set { --- -- Protects a path segment, to prevent it from interfering with the --- url parsing. --- @param s binary string to be encoded. --- @return escaped representation of string binary. +-- URL parsing. +-- @param s Binary string to be encoded. +-- @return Escaped representation of string. local function protect_segment(s) return string.gsub(s, "([^A-Za-z0-9_])", function (c) if segment_set[c] then return c @@ -52,9 +52,9 @@ end --- -- Builds a path from a base path and a relative path --- @param base_path a base path. --- @param relative_path a relative path. --- @return corresponding absolute path. +-- @param base_path A base path. +-- @param relative_path A relative path. +-- @return The corresponding absolute path. ----------------------------------------------------------------------------- local function absolute_path(base_path, relative_path) if string.sub(relative_path, 1, 1) == "/" then return relative_path end @@ -82,8 +82,8 @@ end --- -- Encodes a string into its escaped hexadecimal representation. --- @param s binary string to be encoded. --- @return escaped representation of string binary. +-- @param s Binary string to be encoded. +-- @return Escaped representation of string. ----------------------------------------------------------------------------- function escape(s) return string.gsub(s, "([^A-Za-z0-9_])", function(c) @@ -93,9 +93,9 @@ end --- --- Encodes a string into its escaped hexadecimal representation. --- @param s binary string to be encoded. --- @return escaped representation of string binary. +-- Decodes an escaped hexadecimal string. +-- @param s Hexadecimal-encoded string. +-- @return Decoded string. ----------------------------------------------------------------------------- function unescape(s) return string.gsub(s, "%%(%x%x)", function(hex) @@ -106,20 +106,25 @@ end --- -- Parses a URL and returns a table with all its parts according to RFC 2396. --- \n\n --- The following grammar describes the names given to the URL parts.\n --- ::= :///;?#\n --- ::= @:\n --- ::= [:]\n --- :: = {/}\n --- \n\n --- Obs: the leading '/' in {/} is considered part of . --- @param url uniform resource locator of request --- @param default table with default values for each field --- @return a table with the following fields, where RFC naming conventions have +-- +-- The following grammar describes the names given to the URL parts. +-- +-- ::= :///;?# +-- ::= @: +-- ::= [:] +-- :: = {/} +-- +-- +-- The leading / in / is considered part of +-- . +-- @param url URL of request. +-- @param default Table with default values for each field. +-- @return A table with the following fields, where RFC naming conventions have -- been preserved: --- scheme, authority, userinfo, user, password, host, port, --- path, params, query, fragment. +-- scheme, authority, userinfo, +-- user, password, host, +-- port, path, params, +-- query, and fragment. ----------------------------------------------------------------------------- function parse(url, default) -- initialize default parameters @@ -171,10 +176,10 @@ end --- -- Rebuilds a parsed URL from its components. --- \n\n +-- -- Components are protected if any reserved or unallowed characters are found. --- @param parsed parsed URL, as returned by parse. --- @return a string with the corresponding URL. +-- @param parsed Parsed URL, as returned by parse. +-- @return A string with the corresponding URL. ----------------------------------------------------------------------------- function build(parsed) local ppath = parse_path(parsed.path or "") @@ -202,10 +207,10 @@ function build(parsed) end --- --- Builds a absolute URL from a base and a relative URL according to RFC 2396. --- @param base_url a base URL. --- @param relative_url a relative URL. --- @return corresponding absolute URL. +-- Builds an absolute URL from a base and a relative URL according to RFC 2396. +-- @param base_url A base URL. +-- @param relative_url A relative URL. +-- @return The corresponding absolute URL. ----------------------------------------------------------------------------- function absolute(base_url, relative_url) if type(base_url) == "table" then @@ -241,8 +246,8 @@ end --- -- Breaks a path into its segments, unescaping the segments. --- @param path a path to break. --- @return a table with one entry per segment. +-- @param path A path to break. +-- @return A table with one entry per segment. ----------------------------------------------------------------------------- function parse_path(path) local parsed = {} @@ -259,9 +264,9 @@ end --- -- Builds a path component from its segments, escaping protected characters. --- @param parsed path segments. --- @param unsafe if true, segments are not protected before path is built. --- @return corresponding path string +-- @param parsed Path segments. +-- @param unsafe If true, segments are not protected before path is built. +-- @return The corresponding path string ----------------------------------------------------------------------------- function build_path(parsed, unsafe) local path = "" @@ -291,14 +296,14 @@ end --- -- Breaks a query string into name/value pairs. --- \n\n --- This function takes a of the form name1=value1&name2=value2... +-- +-- This function takes a of the form +-- "name1=value1&name2=value2" -- and returns a table containing the name-value pairs, with the name as the key --- and the value as its associated value. The table corresponding to the above --- would have two entries: table["name1"]="value1" and --- table["name2"]="value2". --- @param query string (name=value&name=value ...). --- @return table where name=value is table['name'] = value. +-- and the value as its associated value. +-- @param query Query string. +-- @return A table of name-value pairs following the pattern +-- table["name"] = value. ----------------------------------------------------------------------------- function parse_query(query) local parsed = {} @@ -329,11 +334,12 @@ function parse_query(query) end --- --- Builds a query string from dictionary based table. --- \n\n --- This is the inverse of parse_query. --- @param query dictionary table where table['name'] = value. --- @return query string (name=value&name=value ...) +-- Builds a query string from a table. +-- +-- This is the inverse of parse_query. +-- @param query A dictionary table where table['name'] = +-- value. +-- @return A query string (like "name=value2&name=value2"). ----------------------------------------------------------------------------- function build_query(query) local qstr = ""