Brief copyediting of NSEDoc for modules.

nselib/afp.lua

@@ -4,11 +4,11 @@
 -- still missing several functions.
 --
 -- The library currently supports
---  o Authentication using the DHX UAM (CAST128)
+-- * Authentication using the DHX UAM (CAST128)
---  o File reading and writing
+-- * File reading and writing
---  o Listing sharepoints
+-- * Listing sharepoints
---  o Listing directory contents
+-- * Listing directory contents
---  o Querying ACLs and mapping user identities (UIDs)
+-- * Querying ACLs and mapping user identities (UIDs)
 --
 -- The library was built based on the following reference:
 -- http://developer.apple.com/mac/library/documentation/Networking/Reference/AFP_Reference/Reference/reference.html
@@ -17,20 +17,20 @@
 -- Most functions have been tested against both Mac OS X 10.6.2 and Netatalk 2.0.3
 --
 -- The library contains the following four classes
---  o Response 
+-- * <code>Response</code>
---    - A class used as return value by functions in the Proto class
+-- ** A class used as return value by functions in the <code>Proto</code> class.
---    - The response class acts as a wrapper and holds the response data and any error information
+-- ** The response class acts as a wrapper and holds the response data and any error information.
---  o Proto 
+-- * <code>Proto</code>
---    - This class contains all the AFP specific functions and calls
+-- ** This class contains all the AFP specific functions and calls.
---    - The functions can be accessed directly but the preferred method is through the Helper class
+-- ** The functions can be accessed directly but the preferred method is through the <code>Helper</code> class.
---    - The function names closely resemble those described in the Apple documentation
+-- ** The function names closely resemble those described in the Apple documentation.
---    - Some functions may lack some of the options outlined in Apple's documentation
+-- ** Some functions may lack some of the options outlined in Apple's documentation.
---  o Helper
+-- * <code>Helper</code>
---    - The helper class wraps the Proto class using functions with a more descriptive name
+-- ** The helper class wraps the <code>Proto</code> class using functions with a more descriptive name.
---    - Functions are task oriented eg. ReadFile and usually call several functions in the Proto class
+-- ** Functions are task-oriented. For example, <code>ReadFile</code> and usually call several functions in the <code>Proto</code> class.
---    - The purpose of this class is to give developers easy access to some of the common AFP tasks
+-- ** The purpose of this class is to give developers easy access to some of the common AFP tasks.
---  o Util
+-- * <code>Util</code>
---    - The util class contains a number of static functions mainly used to convert data
+-- ** The <code>Util</code> class contains a number of static functions mainly used to convert data.
 --
 -- The following information will describe how to use the AFP Helper class to communicate with an AFP server.
 --

nselib/asn1.lua

@@ -1,6 +1,7 @@
---- ASN1 functions.
+---
+-- ASN.1 functions.
 --
--- Large chunks of this code have been ripped right out from snmp.lua
+-- Large chunks of this code have been ripped right out from <code>snmp.lua</code>.
 --
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 --

nselib/base64.lua

@@ -1,4 +1,6 @@
---- Base64 encoding and decoding. Follows RFC 4648.
+---
+-- Base64 encoding and decoding. Follows RFC 4648.
+--
 -- @author Philip Pickering <pgpickering@gmail.com>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 

nselib/bin.luadoc

@@ -1,4 +1,5 @@
---- Pack and unpack binary data.
+---
+-- Pack and unpack binary data.
 --
 -- A problem script authors often face is the necessity of encoding values
 -- into binary data. For example after analyzing a protocol the starting 

nselib/bit.luadoc

@@ -1,4 +1,5 @@
---- Bitwise operations on integers.
+---
+-- Bitwise operations on integers.
 --
 -- Lua does not provide bitwise logical operations. Since they are often useful
 -- for low-level network communication, Reuben Thomas' BitLib

nselib/comm.lua

@@ -1,4 +1,5 @@
---- Common communication functions for network discovery tasks like
+---
+-- Common communication functions for network discovery tasks like
 -- banner grabbing and data exchange.
 --
 -- The functions in this module return values appropriate for use with

nselib/datafiles.lua

@@ -1,4 +1,5 @@
---- Read and parse some of Nmap's data files: <code>nmap-protocols</code>,
+---
+-- Read and parse some of Nmap's data files: <code>nmap-protocols</code>,
 -- <code>nmap-rpc</code>, <code>nmap-services</code>, and 
 -- <code>nmap-mac-prefixes</code>.
 --

nselib/db2.lua

@@ -1,45 +1,31 @@
 ---
--- DB2 Library supporting a very limited subset of operations
+-- DB2 Library supporting a very limited subset of operations.
 --
 -- Summary
--- -------
+-- * The library currently provides functionality to: (1) Query the server for
--- 	o The library currently provides functionality to:
+-- basic settings using the code>getServerInfo</code> function of the helper
---		1. Query the server for basic settings using the 
+-- class. (2) Authenticate to a DB2 server using a plain-text username and
---		   <code>getServerInfo</code> function of the helper class
---		2. Authenticate to a DB2 server using a plain-text username and
 -- password.
 --
--- Overview
--- --------
 -- The library contains the following classes:
+-- * <code>DRDA</code>
+-- ** Implements the Distributed Relational Database Architecture class .
+-- * <code>DRDAParameter</code>
+-- ** Implements a number of functions to handle DRDA parameters.
+-- * <code>DDM</code>
+-- ** Implements the DDM portion of the DRDA structure
+-- * <code>Command</code>
+-- ** Provides functions for easy creation of the most common DRDAs.
+-- ** Implemented as a static class that returns an instance of the DRDA.
+-- * <code>Helper</code>
+-- ** A helper class that provides easy access to the rest of the library
+-- * <code>DB2Socket</code>
+-- ** A smallish socket wrapper that provides fundamental buffering
+-- * <code>StringUtil</code>
+-- ** Provides EBCDIC/ASCII conversion functions
 --
---	 o DRDA
---		- Implements the Distributed Relational Database Architecture class 
---
---   o DRDAParameter
---		- Implements a number of functions to handle DRDA parameters
---
---   o DDM
--- 		- Implements the DDM portion of the DRDA structure
---
---	 o Command
---		- Provides functions for easy creation of the most common DRDA's
---		- Implemented as a static class that returns an instance of the DRDA
---
---   o Helper
---		- A helper class that provides easy access to the rest of the library
---
---	 o DB2Socket
---		- A smallish socket wrapper that provides fundamental buffering
---
---   o StringUtil
---		- Provides EBCDIC/ASCII conversion functions
---
---
--- Example
--- -------
 -- The following sample code illustrates how scripts can use the Helper class
--- to interface the library:
+-- to interface with the library:
 --
 -- <code>
 --	db2helper = db2.Helper:new()
@@ -48,14 +34,11 @@
 --	status, err = db2helper:close()
 -- </code>
 --
--- Additional information
--- ----------------------
 -- The implementation is based on packet dumps and the excellent decoding
 -- provided by Wireshark. 
 --
--- There is some documentation over at:
+-- There is some documentation at
--- 	o http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/
+-- http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.db29.doc.drda/db2z_drda.htm.
--- com.ibm.db29.doc.drda/db2z_drda.htm [link spans two lines]
 --
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 -- @author "Patrik Karlsson <patrik@cqure.net>"

nselib/dns.lua

@@ -1,5 +1,7 @@
---- Simple DNS library supporting packet creation, encoding, decoding,
+---
+-- Simple DNS library supporting packet creation, encoding, decoding,
 -- and querying.
+--
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "dns", package.seeall)

nselib/http.lua

@@ -1,4 +1,5 @@
---- Client-side HTTP library.
+---
+-- Client-side HTTP library.
 --
 -- The return value of each function in this module is a table with the
 -- following keys: <code>status</code>, <code>status-line</code>,

nselib/imap.lua

@@ -1,4 +1,6 @@
---- IMAP functions.
+---
+-- IMAP functions.
+--
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "imap", package.seeall)

nselib/ipOps.lua

@@ -1,4 +1,6 @@
---- Utility functions for manipulating and comparing IP addresses.
+---
+-- Utility functions for manipulating and comparing IP addresses.
+--
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 local type     = type

nselib/json.lua

@@ -1,31 +1,22 @@
---- Library methods for handling Json data. It handles 
+---
--- json encoding and decoding
+-- Library methods for handling JSON data. It handles JSON encoding and
+-- decoding according to RFC 4627.
 --
--- There is a test-section at the bottom which shows some example 
+-- There is a test section at the bottom which shows some example 
--- parsing. If you want to parse json, you can test it by pasting sample json
+-- parsing. If you want to parse JSON, you can test it by pasting sample JSON
--- into the TESTS table and run the test() method
+-- into the <code>TESTS</code> table and run the <code>test</code> method
-
+--
--- More info about Json at http://www.ietf.org/rfc/rfc4627.txt
+-- There is a straightforward mapping between JSON and Lua data types. One
-
+-- exception is JSON <code>NULL</code>, which is not the same as Lua
--- !NOTE! Due to some differences between javascript and lua, there are some
+-- <code>nil</code>. (A better match for Lua <code>nil</code> is JavaScript
--- conversion problems for null-values. Null-values in javascript are not equal to 
+-- <code>undefined</code>.) <code>NULL</code> values in JSON are represented by
--- nil values in lua. Nil is more corresponding to javascript 'undefined'.
+-- the special value <code>json.NULL</code>.
-
--- As an example : 
--- Executing the following javascript : var a= {b:null}; alert(a.b + " != " + a.c);
--- yields the string "null != undefined". Assigning a table a nil value in lua basically
--- removes it from the table, without leaving the key in place. I.e, 
--- >a ={b=nil}
--- >print(a.b, a.c)
--- nil	nil
-
--- !!!Therefore, javascript null values are represented by  json.NULL.!!!
 --
 -- @author Martin Holst Swende
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
+
 -- TODO: Unescape/escape unicode
 -- Version 0.4
-
 -- Created 01/25/2010 - v0.1 - created by Martin Holst Swende <martin@swende.se>
 -- Heavily modified 02/22/2010 - v0.3. Rewrote the parser into an OO-form, to not have to handle
 -- all kinds of state with parameters and return values. 

nselib/ldap.lua

@@ -1,4 +1,5 @@
---- Library methods for handling LDAP. 
+---
+-- Library methods for handling LDAP. 
 --
 -- @author Patrik Karlsson
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html

nselib/listop.lua

@@ -1,4 +1,5 @@
---- Functional-style list operations.
+---
+-- Functional-style list operations.
 --
 -- People used to programming in functional languages, such as Lisp
 -- or Haskell, appreciate their handling of lists very much. The

nselib/match.lua

@@ -1,4 +1,5 @@
---- Buffered network I/O helper functions.
+---
+-- Buffered network I/O helper functions.
 --
 -- The functions in this module can be used for delimiting data received by the
 -- <code>nmap.receive_buf</code> function in the Network I/O API (which see).

nselib/mongodb.lua

@@ -1,4 +1,5 @@
---- Library methods for handling MongoDB, creating and parsing packets
+---
+-- Library methods for handling MongoDB, creating and parsing packets.
 --
 -- @author Martin Holst Swende
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html

nselib/msrpc.lua

@@ -1,4 +1,5 @@
---- By making heavy use of the 'smb' library, this library will call various MSRPC 
+---
+-- By making heavy use of the <code>smb</code> library, this library will call various MSRPC 
 --  functions. The functions used here can be accessed 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. 
@@ -8,11 +9,11 @@
 -- <code>start_smb</code> can be called. A session has to be created, then the IPC$ 
 -- tree opened. 
 --
--- Next, the interface has to be bound. The bind() function will take care of that. 
+-- Next, the interface has to be bound. The <code>bind()</code> function will take care of that. 
 --
 -- After that, you're free to call any function that's part of that interface. In
--- other words, if you bind to the SAMR interface, you can only call the samr_
+-- other words, if you bind to the SAMR interface, you can only call the <code>samr_</code>
--- functions, for lsa_ functions, bind to the LSA interface, etc.  Although functions 
+-- functions, for <code>lsa_</code> functions, bind to the LSA interface, etc.  Although functions 
 -- can technically be called in any order, many functions depend on the
 -- value returned by other functions. I indicate those in the function comments, 
 -- so keep an eye out. SAMR functions, for example, require a call to 
@@ -21,8 +22,8 @@
 -- Something to note is that these functions, for the most part, return a whole ton
 -- of stuff in a table; basically, everything that is returned by the function. 
 -- Generally, if you want to know exactly what you have access to, either display the
--- returned data with a print_table-type function, or check the documentation (Samba 4.0's
+-- returned data with a <code>print_table</code>-type function, or check the documentation (Samba 4.0's
--- .idl files (in samba_4.0/source/librpc/idl; see below for link) are what I based 
+-- <code>.idl</code> files (in <code>samba_4.0/source/librpc/idl</code>; see below for link) are what I based 
 -- the names on). 
 --
 -- The parameters for each function are converted to a string of bytes in a process
@@ -37,8 +38,8 @@
 -- deal with the returned values. 
 --
 -- When implementing this, I used Wireshark's output significantly, as well as Samba's
--- "idl" files for reference:
+-- <code>.idl</code> files for reference:
---  http://websvn.samba.org/cgi-bin/viewcvs.cgi/branches/SAMBA_4_0/source/librpc/idl/ 
+--  http://websvn.samba.org/cgi-bin/viewcvs.cgi/branches/SAMBA_4_0/source/librpc/idl/.
 -- I'm not a lawyer, but I don't expect that this is a breach of Samba's copyright -- 
 -- if it is, please talk to me and I'll make arrangements to re-license this or to 
 -- remove references to Samba. 

nselib/msrpcperformance.lua

@@ -1,16 +1,17 @@
----This module is designed to parse the <code>PERF_DATA_BLOCK</code> structure, which is
+---
+-- This module is designed to parse the <code>PERF_DATA_BLOCK</code> structure, which is
 -- stored in the registry under HKEY_PERFORMANCE_DATA. By querying this structure, you can
 -- get a whole lot of information about what's going on. 
 --
 -- To use this from a script, see <code>get_performance_data</code>, it is the only 
--- 'public' function in this module. 
+-- "public" function in this module. 
 --
 -- My primary sources of information were:
 -- * This 1996 journal by Matt Pietrek: <http://www.microsoft.com/msj/archive/S271.aspx>
 -- * The followup article: <http://www.microsoft.com/msj/archive/S2A9.aspx>
 -- * The WinPerf.h header file
 --
--- And my primary inspiration was PsTools, specifically, pstasklist.exe. 
+-- And my primary inspiration was PsTools, specifically, <code>pstasklist.exe</code>. 
 --
 --@author Ron Bowes <ron@skullsecurity.net>
 --@copyright Same as Nmap--See http://nmap.org/book/man-legal.html

nselib/msrpctypes.lua

@@ -1,10 +1,11 @@
----This module was written to marshall parameters for Microsoft RPC (MSRPC) calls. The values passed in and out are based
+---
+-- This module was written to marshall parameters for Microsoft RPC (MSRPC) calls. The values passed in and out are based
 -- on structs defined by the protocol, and documented by Samba developers. For detailed breakdowns of the types, take a 
--- look at Samba 4.0's .idl files. 
+-- look at Samba 4.0's <code>.idl</code> files. 
 --
 -- There is nothing simple about how this all comes together, so I'll take some time to explain how it's done. This
 -- is fairly technical and, when it comes right down to it, unnecessary for how to use these functions (although if you
--- want to WRITE one of these, you best understand it). 
+-- want to write one of these, you best understand it). 
 --
 -- There are base types, like int32 and int16. These are marshalled the way you'd expect (converted to a 4- or
 -- 2-byte little endian string). The only trick with these is that they have to end up aligned on 4-byte boundaries. 
@@ -12,7 +13,7 @@
 -- <code>marshall_int32</code>, <code>marshall_int16</code>, etc. will marshall the base types, and <code>unmarshall_int32</code>, 
 -- <code>unmarshall_int16</code>, etc. will unmarshall them. 
 --
--- Strings are a little bit tricker. A string is preceded by three 32-bit values: the max length, the offset, and
+-- Strings are a little bit trickier. A string is preceded by three 32-bit values: the max length, the offset, and
 -- the length. Additionally, strings may or may not be null terminated, depending on where they're being used. For
 -- more information on strings, see the comments on <code>marshall_unicode</code>. The functions <code>marshall_unicode</code>
 -- and <code>unmarshall_unicode</code> can be used to mashall/unmarshall strings. 
@@ -24,7 +25,7 @@
 -- itself is 0x00000004). If the integer is nil, then it's marshalled as <code>00 00 00 00</code>, which is simply 
 -- a referent_id of 0. 
 --
--- From the perspective of the program, pointers can be marshalled by using the "_ptr" versions of normal functions
+-- From the perspective of the program, pointers can be marshalled by using the "<code>_ptr</code>" versions of normal functions
 -- (for example, <code>marshall_int32_ptr</code> and <code>unmarshall_unicode_ptr</code>. From the perspective
 -- of functions within this module, especially functions for marshalling structs and arrays, the <code>marshall_ptr</code>
 -- and <code>unmarshall_ptr</code> functions should be used. These can marshall any data type; the marshalling function
@@ -64,10 +65,10 @@
 -- left up to functions within this module. Functions within this module should use <code>marshall_array</code> and 
 -- <code>unmarshall_array</code> to interact with arrays. These take callback functions for the datatype being stored
 -- in the array; these callback functions have to be in a particular format, so care should be taken when writing them. 
--- In particular, the first parameter has to be 'location', which is used to separate the header (the part with the 
+-- In particular, the first parameter has to be <code>location</code>, which is used to separate the header (the part with the 
 -- referent_ids) and the body (the part with the pointer data). These are explained more thoroughly in the function headers. 
 --
--- Structs are handled the same as arrays -- the referent_ids and base types go at the top, and the values being pointed to
+-- Structs are handled the same as arrays. The referent_ids and base types go at the top, and the values being pointed to
 -- go at the bottom. An array of struct, as has already been shown, will have all the base types and referent_ids for all the
 -- members at the top, and all the values for all the pointers at the bottom. 
 --
@@ -82,8 +83,8 @@
 -- function the same way <code>unmarshall_array</code> would. This is a bit of a kludge, but it's the best I could come up 
 -- with. 
 --
--- There are different sections in here, which correspond to "families" of types. I modelled these after Samba's .idl files. 
+-- There are different sections in here, which correspond to "families" of types. I modelled these after Samba's <code>.idl</code> files. 
--- MISC corresponds to misc.idl, LSA to lsa.idl, etc. Each of these sections has possible dependencies; for example, SAMR
+-- MISC corresponds to <code>misc.idl</code>, LSA to <code>lsa.idl</code>, etc. Each of these sections has possible dependencies; for example, SAMR
 -- functions use LSA strings, and everything uses SECURITY and MISC. So the order is important -- dependencies have to go 
 -- above the module. 
 --

nselib/mssql.lua

@@ -1,8 +1,6 @@
 ---
--- MSSQL Library supporting a very limited subset of operations
+-- MSSQL Library supporting a very limited subset of operations.
 --
--- Summary
--- -------
 -- The library was designed and tested against Microsoft SQL Server 2005.
 -- However, it should work with versions 7.0, 2000, 2005 and 2008. 
 -- Only a minimal amount of parsers have been added for tokens, column types
@@ -10,45 +8,18 @@
 -- 
 -- The code has been implemented based on traffic analysis and the following
 -- documentation:
--- o TDS Protocol Documentation
+-- * TDS Protocol Documentation: http://www.freetds.org/tds.html.
---   http://www.freetds.org/tds.html
+-- * The JTDS source code: http://jtds.sourceforge.net/index.html.
 --
--- o The JTDS source code
+-- * ColumnInfo: Class containing parsers for column types which are present before the row data in all query response packets. The column information contains information relevant to the data type used to hold the data eg. precision, character sets, size etc.
---   http://jtds.sourceforge.net/index.html
+-- * ColumnData: Class containing parsers for the actual column information.
+-- * Token: Class containing parsers for tokens returned in all TDS responses. A server response may hold one or more tokens with information from the server. Each token has a type which has a number of type specific fields.
+-- * QueryPacket: Class used to hold a query and convert it to a string suitable for transmission over a socket.
+-- * LoginPacket: Class used to hold login specific data which can easily be converted to a string suitable for transmission over a socket.
+-- * TDSStream: Class that handles communication over the Tabular Data Stream protocol used by SQL serve. It is used to transmit the the Query- and Login-packets to the server.
+-- * Helper: Class which facilitates the use of the library by through action oriented functions with descriptive names.
+-- * Util: A "static" class containing mostly character and type conversion functions.
 --
--- Overview
--- --------
--- o ColumInfo - Class containing parsers for column types which are present
---               before the row data in all query response packets. The column
---               information contains information relevant to the data type
---               used to hold the data eg. precision, character sets, size etc.
---
--- o ColumnData - Class containing parsers for the actual column information
---
--- o Token - Class containing parsers for tokens returned in all TDS responses.
---           A server response may hold one or more tokens with information
---           from the server. Each token has a type which has a number of
---           type specific fields.
---
--- o QueryPacket - Class used to hold a query and convert it to a string
---                 suitable for transmission over a socket.
---
--- o LoginPacket - Class used to hold login specific data which can easily
---                 be converted to a string suitable for transmission over
---                 a socket.
---
--- o TDSStream - Class that handles communication over the Tabular Data Stream
---               protocol used by SQL serve. It is used to transmit the the
---			     Query- and Login-packets to the server.
---
--- o Helper	- Class which facilitates the use of the library by through action
---            oriented functions with descriptive names.
---
--- o Util - "static" class containing mostly character and type conversion
---          functions.
---
--- Example
--- -------
 -- The following sample code illustrates how scripts can use the Helper class
 -- to interface the library:
 --
@@ -59,36 +30,14 @@
 -- helper:Disconnect()
 -- <code>
 --
--- Known limitations
+-- Known limitations:
--- -----------------
+-- * The library does not support SSL. The foremost reason being the akward choice of implementation where the SSL handshake is performed within the TDS data block. By default, servers support connections over non SSL connections though. 
--- o The library does not support SSL. The foremost reason being the akward
+-- * Version 7 and ONLY version 7 of the protocol is supported. This should cover Microsoft SQL Server 7.0 and later.
---   choice of implementation where the SSL handshake is performed within
+-- * TDS Responses contain one or more response tokens which are parsed based on their type. The supported tokens are listed in the <code>TokenType</code> table and their respective parsers can be found in the <code>Token</code> class. Note that some token parsers are not fully implemented and simply move the offset the right number of bytes to continue processing of the response.
---   the TDS data block. By default, servers support connections over non
+-- * The library only supports a limited subsets of datatypes and will abort execution and return an error if it detects an unsupported type. The supported data types are listed in the <code>DataTypes</code> table. In order to add additional data types a parser function has to be added to both the <code>ColumnInfo</code> and <code>ColumnData</code> class.
---   SSL connections though. 
+-- * No functionality for languages, localization or characted codepages has been considered or implemented.
---
+-- * The library does database authentication only. No OS authentication or use of the integrated security model is supported.
--- o Version 7 and ONLY version 7 of the protocol is supported. This should 
+-- * Queries using SELECT, INSERT, DELETE and EXEC of procedures have been tested while developing scripts.
---   cover Microsoft SQL Server 7.0 and later.
---
--- o TDS Responses contain one or more response tokens which are parsed based
---   on their type. The supported tokens are listed in the TokenType table and
---   their respective parsers can be found in the Token class. Note that some
---   token parsers are not fully implemented and simply move the offset the 
---   right number of bytes to continue processing of the response.
---
--- o The library only supports a limited subsets of datatypes and will abort
---   execution and return an error if it detects an unsupported type. The
---   supported data types are listed in the DataTypes table. In order to add
---   additional data types a parser function has to be added to both the
---   ColumnInfo and ColumnData class.
---
--- o No functionality for languages, localization or characted codepages has
---   been considered or implemented.
---
--- o The library does database authentication only. No OS authentication or
---   use of the integrated security model is supported.
---
--- o Queries using SELECT, INSERT, DELETE and EXEC of procedures have been
---   tested while developing scripts.
 --
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 --

nselib/mysql.lua

@@ -1,5 +1,6 @@
 ---
--- Simple MySQL Library supporting a very limited subset of operations
+-- Simple MySQL Library supporting a very limited subset of operations.
+--
 -- http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol
 --
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html

nselib/netbios.lua

@@ -1,9 +1,9 @@
---- Creates and parses NetBIOS traffic. The primary use for this is to send
+---
+-- Creates and parses NetBIOS traffic. The primary use for this is to send
 -- NetBIOS name requests. 
 --
 -- @author Ron Bowes <ron@skullsecurity.net>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
------------------------------------------------------------------------
 
 module(... or "netbios", package.seeall)
 

nselib/nmap.luadoc

@@ -1,4 +1,5 @@
---- Interface with Nmap internals.
+---
+-- Interface with Nmap internals.
 --
 -- The <code>nmap</code> module is an interface with Nmap's internal functions
 -- and data structures. The API provides target host details such as port

nselib/nsedebug.lua

@@ -1,3 +1,4 @@
+---
 -- Debugging functions for Nmap scripts. 
 --
 -- This module contains various handy functions for debugging. These should
@@ -11,7 +12,8 @@ local EMPTY = {}; -- Empty constant table
 
 module(... or "nsedebug", package.seeall);
 
----Converts an arbitrary data type into a string. Will recursively convert 
+---
+-- Converts an arbitrary data type into a string. Will recursively convert 
 -- tables. This can be very useful for debugging. 
 --
 --@param data   The data to convert. 

nselib/openssl.luadoc

@@ -1,4 +1,5 @@
---- OpenSSL bindings.
+---
+-- OpenSSL bindings.
 --
 -- This module is a wrapper for OpenSSL functions that provide encryption and
 -- decryption, hashing, and multiprecision integers.

nselib/packet.lua

@@ -1,4 +1,6 @@
---- Facilities for manipulating raw packets.
+---
+-- Facilities for manipulating raw packets.
+--
 -- @author Marek Majkowski <majek04+nse@gmail.com>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 

nselib/pcre.luadoc

@@ -1,4 +1,5 @@
---- Perl Compatible Regular Expressions.
+---
+-- Perl Compatible Regular Expressions.
 --
 -- One of Lua's quirks is its string patterns. While they have great performance
 -- and are tightly integrated into the Lua interpreter, they are very different

nselib/pgsql.lua

@@ -1,13 +1,13 @@
 ---
--- PostgreSQL library supporting both version 2 and version 3 of the protocol
+-- PostgreSQL library supporting both version 2 and version 3 of the protocol.
--- The library currently contains the bare minimum to perform authentication
+-- The library currently contains the bare minimum to perform authentication.
 -- Authentication is supported with or without SSL enabled and using the
--- plain-text or MD5 authentication mechanisms
+-- plain-text or MD5 authentication mechanisms.
 --
--- The PGSQL protocol is explained in detail in the following reference
+-- The PGSQL protocol is explained in detail in the following references.
--- ref: http://developer.postgresql.org/pgdocs/postgres/protocol.html
+-- * http://developer.postgresql.org/pgdocs/postgres/protocol.html
--- ref: http://developer.postgresql.org/pgdocs/postgres/protocol-flow.html
+-- * http://developer.postgresql.org/pgdocs/postgres/protocol-flow.html
--- ref: http://developer.postgresql.org/pgdocs/postgres/protocol-message-formats.html
+-- * http://developer.postgresql.org/pgdocs/postgres/protocol-message-formats.html
 --
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 -- @author "Patrik Karlsson <patrik@cqure.net>"

nselib/pop3.lua

@@ -1,4 +1,6 @@
---- POP3 functions.
+---
+-- POP3 functions.
+--
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 module(... or "pop3",package.seeall)

nselib/proxy.lua

@@ -1,4 +1,6 @@
---- Functions for proxy testing
+---
+-- Functions for proxy testing.
+--
 -- @author Joao Correa <joao@livewire.com.br>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 

nselib/rpc.lua

@@ -1,41 +1,35 @@
 ---
--- RPC Library supporting a very limited subset of operations
+-- RPC Library supporting a very limited subset of operations.
 --
--- Summary
+-- The library works over both the UDP and TCP protocols. A subset of nfs and
--- -------
+-- mountd procedures are supported. The nfs and mountd programs support
--- 	o The library works over both the UDP and TCP protocols
+-- versions 1 through 3. Authentication is supported using the NULL RPC
---	o A subset of nfs and mountd procedures are supported
+-- Authentication protocol
---  o The versions 1 through 3 are supported for the nfs and mountd program
---  o Authentication is supported using the NULL RPC Authentication protocol
 --
--- Overview
--- --------
 -- The library contains the following classes:
---   o Comm 
+-- * <code>Comm </code>
---   		- Handles network connections
+-- ** Handles network connections.
---		- Handles low-level packet sending, recieving, decoding and encoding
+-- ** Handles low-level packet sending, recieving, decoding and encoding.
---		- Stores rpc programs info: socket, protocol, program name, id and version
+-- ** Stores rpc programs info: socket, protocol, program name, id and version.
---		- Used by Mount, NFS, RPC and Portmap
+-- ** Used by Mount, NFS, RPC and Portmap.
---   o Portmap
+-- * <code>Portmap</code>
---		- Containes RPC constants
+-- ** Contains RPC constants.
---		- Handles communication with the portmap RPC program
+-- ** Handles communication with the portmap RPC program.
---   o Mount 
+-- * <code>Mount</code>
---		- Handles communication with the mount RPC program
+-- ** Handles communication with the mount RPC program.
---   o NFS 
+-- * <code>NFS</code>
---		- Handles communication with the nfs RPC program
+-- ** Handles communication with the nfs RPC program.
---   o Helper 
+-- * <code>Helper</code>
---		- Provides easy access to common RPC functions
+-- ** Provides easy access to common RPC functions.
---		- Implemented as a static class where most functions accept host 
+-- ** Implemented as a static class where most functions accept host and port parameters.
---                and port parameters
+-- * <code>Util</code>
---   o Util
+-- ** Mostly static conversion routines.
---	 	- Mostly static conversion routines
 --
--- The portmapper dynamically allocates tcp/udp ports to RPC programs. So in
+-- The portmapper dynamically allocates TCP/UDP ports to RPC programs. So in
 -- in order to request a list of NFS shares from the server we need to:
---  o Make sure that we can talk to the portmapper on port 111 tcp or udp
+-- * Make sure that we can talk to the portmapper on port 111 TCP or UDP.
---  o Query the portmapper for the ports allocated to the NFS program
+-- * Query the portmapper for the ports allocated to the NFS program.
---  o Query the NFS program for a list of shares on the ports returned by the
+-- * Query the NFS program for a list of shares on the ports returned by the portmap program.
---    portmap program.
 --
 -- The Helper class contains functions that facilitate access to common
 -- RPC program procedures through static class methods. Most functions accept
@@ -43,9 +37,7 @@
 -- get the correct RPC program port, the port supplied to these functions
 -- should be the rpcbind port 111/tcp or 111/udp.
 --
--- Example
+-- The following sample code illustrates how scripts can use the <code>Helper</code> class
--- -------
--- The following sample code illustrates how scripts can use the Helper class
 -- to interface the library:
 --
 -- <code>
@@ -61,9 +53,7 @@
 -- end
 -- </code>
 --
--- Additional information
+-- RPC transaction IDs (XID) are not properly implemented as a random ID is
--- ----------------------
--- RPC transaction ID's (XID) are not properly implemented as a random ID is
 -- generated for each client call. The library makes no attempt to verify
 -- whether the returned XID is valid or not.
 --

nselib/shortport.lua

@@ -1,7 +1,9 @@
---- Functions for building short portrules.
+---
+-- Functions for building short portrules.
 --
 -- 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
 
 module(... or "shortport", package.seeall)

nselib/smb.lua

@@ -1,4 +1,5 @@
----Implements functionality related to Server Message Block (SMB, also known 
+---
+-- Implements functionality related to Server Message Block (SMB, also known 
 -- as CIFS) traffic, which is a Windows protocol.
 --
 -- SMB traffic is normally sent to/from ports 139 or 445 of Windows systems. Other systems

nselib/smbauth.lua

@@ -1,7 +1,8 @@
----This module takes care of the authentication used in SMB (LM, NTLM, LMv2, NTLMv2). 
+---
+-- This module takes care of the authentication used in SMB (LM, NTLM, LMv2, NTLMv2). 
+--
 -- There is a lot to this functionality, so if you're interested in how it works, read
 -- on. 
---
 -- In SMB authentication, there are two distinct concepts. Each will be dealt with
 -- separately. There are:
 -- * Stored hashes
@@ -9,13 +10,13 @@
 --
 -- What's confusing is that the same names are used for each of those. 
 --
--- Stored Hashes
+-- Stored Hashes:
 -- Windows stores two types of hashes: Lanman and NT Lanman (or NTLM). Vista and later
 -- store NTLM only. Lanman passwords are divided into two 7-character passwords and 
 -- used as a key in DES, while NTLM is converted to unicode and MD4ed. 
 --
--- The stored hashes can be dumped in a variety of ways (pwdump6, fgdump, metasploit's
+-- The stored hashes can be dumped in a variety of ways (pwdump6, fgdump, Metasploit's
--- priv module, smb-psexec.nse, etc). Generally, two hashes are dumped together 
+-- <code>priv</code> module, <code>smb-psexec.nse</code>, etc). Generally, two hashes are dumped together 
 -- (generally, Lanman:NTLM). Sometimes, Lanman is empty and only NTLM is given. Lanman
 -- is never required. 
 --
@@ -24,7 +25,7 @@
 -- can be passed, in the form of Lanman:NTLM, or a single hash, which is assumed to
 -- be NTLM. 
 --
--- Authentication
+-- Authentication:
 -- There are four types of authentication. Confusingly, these have the same names as
 -- stored hashes, but only slight relationships. The four types are Lanmanv1, NTLMv1, 
 -- Lanmanv2, and NTLMv2. By default, Lanmanv1 and NTLMv1 are used together in most 
@@ -77,7 +78,7 @@
 --                   protocol altogether!). If you're using an extremely old system, you might need to set 
 --                   this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible.  
 --                   For information, see <code>smbauth.lua</code>. 
---@args smbnoguest   Set to 'true' or '1' to disable usage of the 'guest' account. 
+--@args smbnoguest   Set to <code>true</code> or <code>1</code> to disable usage of the 'guest' account. 
 
 module(... or "smbauth", package.seeall)
 

nselib/snmp.lua

@@ -1,11 +1,9 @@
---- SNMP functions.
+---
+-- SNMP functions.
 --
 -- @args snmpcommunity The community string to use. If not given, it is
 -- <code>"public"</code>, or whatever is passed to <code>buildPacket</code>.
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
---
---
--- 
 
 module(... or "snmp",package.seeall)
 

nselib/ssh1.lua

@@ -1,6 +1,7 @@
---- Functions for the SSH-1 protocol.
+---
+-- Functions for the SSH-1 protocol. This module also contains functions for
+-- formatting key fingerprints.
 --
--- This module also contains functions for formatting key fingerprints.
 -- @author Sven Klemm <sven@c3d2.de>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 

nselib/ssh2.lua

@@ -1,4 +1,6 @@
---- Functions for the SSH-2 protocol.
+---
+-- Functions for the SSH-2 protocol.
+--
 -- @author Sven Klemm <sven@c3d2.de>
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 

nselib/stdnse.lua

@@ -1,7 +1,7 @@
---- Standard Nmap Scripting Engine functions.
+---
+-- Standard Nmap Scripting Engine functions. This module contains various handy
+-- functions that are too small to justify modules of their own.
 --
--- This module contains various handy functions that are too small to justify
--- modules of their own.
 -- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html
 
 local assert = assert;

nselib/strbuf.lua

@@ -1,4 +1,5 @@
---- String buffer facilities.
+---
+-- String buffer facilities.
 --
 -- Lua's string operations are very flexible and offer an easy-to-use way to
 -- manipulate strings. Concatenation using the <code>..</code> operator is such

nselib/strict.lua

@@ -1,13 +1,14 @@
---- Strict Declared Global library.
+---
+-- Strict declared global library. Checks for undeclared global variables
+-- during runtime execution.
 --
--- Checks for undeclared global variables during runtime execution. This module
+-- This module places the <code>strict</code> function in the global
--- places the 'strict' function in the global environment. The strict function
+-- environment. The strict function allows a script to add runtime checking so
--- allows a script to add runtime checking so that undeclared globals cause
+-- that undeclared globals cause an error to be raised. This is useful for
--- an error to be raised. This is useful for finding accidental use of globals
+-- finding accidental use of globals when local was intended.
--- when local was intended.
 --
--- A global variable is considered 'declared' if the script makes an assignment
+-- A global variable is considered "declared" if the script makes an assignment
--- to the global name (even nil) in the file scope.
+-- to the global name (even <code>nil</code>) in the file scope.
 --
 -- @class module
 -- @name strict

nselib/tab.lua

@@ -1,4 +1,5 @@
---- Arrange output into tables.
+---
+-- Arrange output into tables.
 --
 -- This module provides NSE scripts with a way to output structured tables
 -- similar to what <code>NmapOutputTable.cc</code> provides.

nselib/unpwdb.lua

@@ -1,4 +1,5 @@
---- Username/password database library.
+---
+-- Username/password database library.
 --
 -- The <code>usernames</code> and <code>passwords</code> functions return
 -- multiple values for use with exception handling via

nselib/url.lua

@@ -1,4 +1,6 @@
---- URI parsing, composition, and relative URL resolution.
+---
+-- URI parsing, composition, and relative URL resolution.
+--
 -- @author Diego Nehab
 -- @author Eddie Bell <ejlbell@gmail.com>
 

scripts/pgsql-brute.nse

@@ -1,5 +1,5 @@
 description = [[
-Performs password guessing against Postgresql.
+Performs password guessing against PostgreSQL.
 ]]
 
 ---