Proofread and format the smb-* scripts. This was mostly done by Ron already.

scripts/smb-enumdomains.nse

@@ -1,15 +1,16 @@
 id = "MSRPC: List of domains"
-description = [[ Attempts to enumerate domains on a system, along with their policies. This will likely
+description = [[
- only work without credentials against Windows 2000. 
+Attempts to enumerate domains on a system, along with their policies. This will likely only work without credentials against Windows 2000. 
 
-After the initial bind() to SAMR, the sequence of calls is:
+After the initial <code>bind()</code> to SAMR, the sequence of calls is:
-* Connect4() -- get a connect_handle
+* <code>Connect4()</code>: get a connect_handle
-* EnumDomains() -- get a list of the domains (stop here if you just want the names)
+* <code>EnumDomains()</code>: get a list of the domains (stop here if you just want the names).
-* QueryDomain() -- get the sid for the domain
+* <code>QueryDomain()</code>: get the SID for the domain.
-* OpenDomain() -- get a handle for each domain
+* <code>OpenDomain()</code>: get a handle for each domain.
-* QueryDomainInfo2() -- get the domain information
+* <code>QueryDomainInfo2()</code>: get the domain information.
-* QueryDomainUsers() -- get a list of the users in the domain
+* <code>QueryDomainUsers()</code>: get a list of the users in the domain.
 ]]
+
 ---
 --@usage
 -- nmap --script smb-enumdomains.nse -p445 <host>
@@ -38,38 +39,35 @@ After the initial bind() to SAMR, the sequence of calls is:
 -- |     |_  Password complexity requirements do not exist
 -- |_    |_  Administrator account cannot be locked out
 -- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
-description = "Tries calling the EnumDomains() and QueryDomainInfo2() RPC function to obtain a list of domains/policies."
 author = "Ron Bowes"
 copyright = "Ron Bowes"
 license = "Same as Nmap--See http://nmap.org/book/man-legal.html"

scripts/smb-enumsessions.nse

@@ -4,12 +4,12 @@ Enumerates the users logged into a system either locally, through a remote deskt
 services), or through a SMB share.
 
 Enumerating the local and terminal services users is done by reading the remote registry. Keys under
-HKEY_USERS are SIDs that represent the currently logged in users, and those SIDs can be converted
+<code>HKEY_USERS</code> are SIDs that represent the currently logged in users, and those SIDs can be converted
-to proper names by using the LsaLookupSids() function. Doing this requires any access higher than
+to proper names by using the <code>LsaLookupSids()</code> function. Doing this requires any access higher than
 anonymous (guests, users, or administrators are all able to perform this request on the operating
 systems I tested). 
 
-Enumerating SMB connections is done using the srvsvc.netsessenum() function, which returns who's
+Enumerating SMB connections is done using the <code>srvsvc.netsessenum()</code> function, which returns who's
 logged in, when they logged in, and how long they've been idle for. Unfortunately, I couldn't find
 a way to get the user's domain with this function, so the domain isn't printed. The level of access
 required for this varies between Windows versions, but in Windows 2000 anybody (including the 
@@ -23,6 +23,7 @@ I learned the idea and technique for this from sysinternals' tool, PsLoggedOn.ex
 function calls to what they use, so thanks go out to them. Thanks also to Matt, for giving me the 
 idea to write this one. 
 ]]
+
 ---
 --@usage
 -- nmap --script smb-enumsessions.nse -p445 <host>
@@ -36,40 +37,37 @@ idea to write this one.
 -- |  |_ DOMAIN\rbowes since 2008-10-20 09:03:23
 -- |  Active SMB Sessions:
 -- |_ |_ ADMINISTRATOR is connected from 10.100.254.138 for [just logged in, it's probably you], idle for [not idle]
---
+-- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 id = "MSRPC: NetSessEnum()"
-description = "Tries calling the NetSessEnum() RPC function to get a list of active sessions"
 author = "Ron Bowes"
 copyright = "Ron Bowes"
 license = "Same as Nmap--See http://nmap.org/book/man-legal.html"
@@ -91,12 +89,12 @@ hostrule = function(host)
 
 end
 
----Attempts to enumerate the shares on a remote system using MSRPC calls. This will likely fail 
+---Attempts to enumerate the sessions on a remote system using MSRPC calls. This will likely fail 
 -- against a modern system, but will succeed against Windows 2000. 
 --
 --@param host The host object. 
---@return (status, result) If status is false, result is an error string. Otherwise, result is 
+--@return Status (true or false).
---        a list of all shares on a system. 
+--@return List of sessions (if status is true) or an an error string (if status is false).
 local function srvsvc_enum_sessions(host)
 	local i
 	local status, smbstate
@@ -132,7 +130,7 @@ end
 -- that access the registry. To perform this check, guest access or higher is required. 
 --
 --@param host The host object. 
---@return An array of tables, each table representing a user and containing values for 'name', 'domain', and 'changed_date' (representing
+--@return An array of user tables, each with the keys <code>name</code>, <code>domain</code>, and <code>changed_date</code> (representing
 --        when they logged in). 
 local function winreg_enum_rids(host)
 	local i, j

scripts/smb-enumshares.nse

@@ -1,23 +1,26 @@
 id = "MSRPC: List of shares"
 description = [[
-Attempts to list shares using the srvsvc.NetShareEnumAll() MSRPC function, then 
+Attempts to list shares using the <code>srvsvc.NetShareEnumAll()</code> MSRPC function, then 
-retrieve more information about each share using srvsvc.NetShareGetInfo(). Running
+retrieve more information about each share using <code>srvsvc.NetShareGetInfo()</code>.
-NetShareEnumAll() will work anonymously on Windows 2000, and requires a user level 
+
-account on any other Windows version. Calling NetShareGetInfo() requires an 
+Running
+<code>NetShareEnumAll()</code> will work anonymously on Windows 2000, and requires a user-level 
+account on any other Windows version. Calling <code>NetShareGetInfo()</code> requires an 
 administrator account on every version of Windows I tested. 
 
-Although NetShareEnumAll() is restricted on certain systems, actually connecting to
+Although <code>NetShareEnumAll()</code> is restricted on certain systems, actually connecting to
-a share to check if it exists will always work. So, if NetShareEnumAll() fails, a 
+a share to check if it exists will always work. So, if <code>NetShareEnumAll()</code> fails, a 
 list of common shares will be attempted. 
 
 After a list of shares is found, whether or not it's complete, we attempt to connect
-to each of them anonymously, which lets us divide them into "anonymous" and 
+to each of them anonymously, which lets us divide them into the classes
-"restricted". 
+"anonymous" and "restricted." 
 
-When possible, once the list of shares is determined, NetShareGetInfo() is called 
+When possible, once the list of shares is determined, <code>NetShareGetInfo()</code> is called 
 to get additional information on the share. Odds are this will fail, unless we're 
 doing an authenticated test. 
 ]]
+
 ---
 --@usage
 -- nmap --script smb-enumshares.nse -p445 <host>
@@ -55,35 +58,33 @@ doing an authenticated test.
 -- |     |_ Users: 0, Max: <unlimited>
 -- |_    |_ Path: C:\
 -- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 author = "Ron Bowes"
@@ -111,8 +112,8 @@ end
 -- against a modern system, but will succeed against Windows 2000. 
 --
 --@param host The host object. 
---@return (status, result) If status is false, result is an error string. Otherwise, result is 
+--@return Status (true or false).
---        a list of all shares on a system. 
+--@return List of shares (if status is true) or an an error string (if status is false).
 local function samr_enum_shares(host)
 
 	local status, smbstate
@@ -147,10 +148,10 @@ end
 ---Attempts to connect to a list of shares as the anonymous user, returning which ones
 -- it has and doesn't have access to. 
 --
---@param host   The host object
+--@param host   The host object.
---@param shares An array of shares to check
+--@param shares An array of shares to check.
---@return (allowed_shares, denied_shares) Lists of shares we can and can't access, 
+--@return List of shares we're allowed to access.
---        but all of which exist. 
+--@return List of shares that exist but are denied to us.
 function check_shares(host, shares)
 	local smbstate
     local i
@@ -214,8 +215,8 @@ end
 -- administrative access. 
 --
 --@param host The host object. 
---@return (status, result) If status is false, result is an error string. Otherwise, result is 
+--@return Status (true or false).
---        a list of all shares on a system. 
+--@return List of shares (if status is true) or an an error string (if status is false).
 local function get_share_info(host, name)
 	local status, smbstate
 	local response = {}

scripts/smb-enumusers.nse

@@ -1,46 +1,44 @@
 id = "MSRPC: List of user accounts"
 description = [[
 Attempts to enumerate the users on a remote Windows system, with as much
-information as possible, through a variety of techniques (over SMB + MSRPC,
+information as possible, through a variety of techniques (over SMB and MSRPC,
 which uses port 445 or 139). Some functions in SAMR are used to enumerate
-users, and some bruteforce guessing using LSA functions is attempted. 
+users, and some brute-force guessing using LSA functions is attempted. 
 
-One technique used is calling the QueryDisplayInfo() function in the SAMR library. 
+One technique used is calling the <code>QueryDisplayInfo()</code> function in the SAMR library. 
 If this succeeds, it will return a detailed list of users. This can be done
 anonymously against Windows 2000, and with a user-level account on other Windows
 versions (but not with a guest-level account). 
 
 To perform this test, the following functions are used:
-
+* <code>Bind()</code>: bind to the SAMR service.
-	* Bind() -- bind to the SAMR service
+* <code>Connect4()</code>: get a connect_handle.
-	* Connect4() -- get a connect_handle
+* <code>EnumDomains()</code>: get a list of the domains.
-	* EnumDomains() -- get a list of the domains
+* <code>QueryDomain()</code>: get the sid for the domain.
-	* QueryDomain() -- get the sid for the domain
+* <code>OpenDomain()</code>: get a handle for each domain.
-	* OpenDomain() -- get a handle for each domain
+* <code>QueryDisplayInfo()</code>: get the list of users in the domain.
-	* QueryDisplayInfo() -- get the list of users in the domain
+* <code>Close()</code>: Close the domain handle.
-	* Close() -- Close the domain handle
+* <code>Close()</code>: Close the connect handle.
-	* Close() -- Close the connect handle
-
 The advantage of this technique is that a lot of details are returned, including
 the full name and description; the disadvantage is that it requires a user-level
 account on every system except for Windows 2000. Additionally, it only pulls actual
-user accounts, not groups or aliasts. 
+user accounts, not groups or aliases. 
 
-Regardless of whether or not this succeeds, a second technique is used to pull
+Regardless of whether this succeeds, a second technique is used to pull
 user accounts, called LSA bruteforcing. LSA bruteforcing can be done anonymously
 against Windows 2000, and requires a guest account or better on other systems. 
-It has the advantage of running with less permissions, and will also find more 
+It has the advantage of running with less permission, and will also find more 
-account types (ie, groups, aliases, etc). The disadvantages is that it returns 
+account types (i.e., groups, aliases, etc.). The disadvantages is that it returns 
-less information, and that, because it's a bruteforce, it's possible to miss
+less information, and that, because it's a brute-force guess, it's possible to miss
 accounts. 
-\n\n
+
-This isn't a bruteforce in the common sense, however; it's a bruteforce of users' 
+This isn't a brute-force technique in the common sense, however: it's a brute-forcing of users' 
 RIDs. A user's RID is a value (generally 500, 501, or 1000+) that uniquely identifies
 a user on a domain or system. An LSA function is exposed which lets us convert the RID
-(say, '1000') to the username (say, 'Ron'). So, the bruteforce will essentially try
+(say, 1000) to the username (say, "Ron"). So, the technique will essentially try
-converting 1000 to a name, 1001, 1002, etc., until we think we're done. 
+converting 1000 to a name, then 1001, 1002, etc., until we think we're done. 
-\n\n
+
-I break the users into 5-RID groups, and check them individually (checking too many
+I break the users into groups of 5 RIDs, and check them individually (checking too many
 at once causes problems). I continue checking until I reach 1100, and get an empty
 group. This probably isn't the most effective way, but it seems to work. 
 It might be a good idea to modify this, in the future, with some more
@@ -49,27 +47,25 @@ and I got these results: 500, 501, 1000, 1030, 1031, 1053, 1054, 1055,
 1056, 1057, 1058, 1059, 1060, 1061, 1062, 1063, 1064, 1065, 1066, 1067, 1070, 
 1075, 1081, 1088, 1090. The jump from 1000 to 1030 is quite large and can easily 
 result in missing accounts, in an automated check. 
-\n\n
+
 Before attempting this conversion, the SID of the server has to be determined. 
-The SID is determined by doing the reverse operation -- converting a name into 
+The SID is determined by doing the reverse operation, that is, converting a name into 
 a RID. The name is determined by looking up any name present on the system. 
-In this script, I try looking up:
+In this script, I try:
-\n\n
+* The computer name and domain name, returned in <code>SMB_COM_NEGOTIATE</code>;
-<ul>
+* An nbstat query to get the server name and the user currently logged in; and
-	<li>The computer name / domain name, returned in SMB_COM_NEGOTIATE
+* Some common names: "administrator", "guest", and "test".
-	<li>An nbstat query to get the server name and the currently loggeed in user
+
-	<li>Some common names ("administrator", "guest", and "test")
-</ul>
-\n\n
 In theory, the computer name should be sufficient for this to always work, and
 so far has in my tests, but I included the rest of the names for good measure. 
-\n\n
+
 The names and details from both of these techniques are merged and displayed.
-If the output is verbose, then extra details. The output is ordered alphabetically. 
+If the output is verbose, then extra details are shown. The output is ordered alphabetically. 
-\n\n
+
 Credit goes out to the enum.exe, sid2user.exe, and user2sid.exe programs, 
 the code I wrote for this is largely based on the techniques used by them.
 ]]
+
 ---
 -- @usage
 -- nmap --script smb-enumusers.nse -p445 <host>
@@ -114,36 +110,33 @@ the code I wrote for this is largely based on the techniques used by them.
 -- |    |_ Type: Alias
 -- |_   |_ Domain: LOCALSYSTEM
 -- 
---
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
---                   are NOT understood. To set a domain, use the smbdomain argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 author = "Ron Bowes"
@@ -170,8 +163,11 @@ end
 ---Attempt to enumerate users through SAMR methods. See the file description for more information. 
 --
 --@param host The host object. 
---@return (status, result) If status is false, result is an error message. Otherwise, result is an
+--@return Status (true or false).
---        array of tables. Each table contains a 'name', 'domain', 'fullname', 'rid', and 'description'. 
+--@return Array of user tables (if status is true) or an an error string (if
+--status is false). Each user table contains the fields <code>name</code>,
+--<code>domain</code>, <code>fullname</code>, <code>rid</code>, and
+--<code>description</code>.
 local function enum_samr(host)
 
 	stdnse.print_debug(3, "Entering enum_samr()")
@@ -284,8 +280,10 @@ end
 ---Attempt to enumerate users through LSA methods. See the file description for more information. 
 --
 --@param host The host object. 
---@return (status, result) If status is false, result is an error message. Otherwise, result is an
+--@return Status (true or false).
---        array of tables. Each table contains a 'name', 'domain', and 'rid'. 
+--@return Array of user tables (if status is true) or an an error string (if
+--status is false). Each user table contains the fields <code>name</code>,
+--<code>domain</code>, and <code>rid</code>.
 local function enum_lsa(host)
 
 	local smbstate

scripts/smb-os-discovery.nse

@@ -1,11 +1,10 @@
 id = "OS from SMB"
 description = [[
 Attempts to determine the operating system over the SMB protocol (ports 445 and
-139).  Although the standard smb arguments can be used (for username/password), and
+139).
-are respected by this script, they likely won't change the outcome in any meaningful 
-way. 
 
-See nselib/smb.lua for more information on this protocol. 
+Although the standard <code>smb*</code> script arguments can be used, 
+they likely won't change the outcome in any meaningful way. 
 ]]
 
 ---
@@ -19,35 +18,33 @@ See nselib/smb.lua for more information on this protocol.
 -- |  Name: WORKGROUP\TEST1
 -- |_ System time: 2008-09-09 20:55:55 UTC-5
 -- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 author = "Ron Bowes"
@@ -70,9 +67,9 @@ hostrule = function(host)
 
 end
 
---- Converts numbered Windows versions (5.0, 5.1) to the names (Windows 2000, Windows XP). 
+--- Converts numbered Windows version strings (<code>"Windows 5.0"</code>, <code>"Windows 5.1"</code>) to names (<code>"Windows 2000"</code>, <code>"Windows XP"</code>). 
---@param os The name of the OS
+--@param os The numbered OS version.
---@return The actual name of the OS (or the same as the 'os' parameter)
+--@return The actual name of the OS (or the same as the <code>os</code> parameter if no match was found).
 function get_windows_version(os)
 
 	if(os == "Windows 5.0") then

scripts/smb-security-mode.nse

@@ -4,30 +4,28 @@ Returns information about the SMB security level determined by SMB.
 
 Here is how to interpret the output:
 
-User-level security: Each user has a separate username/password that is used
+User-level authentication: Each user has a separate username/password that is used
 to log into the system. This is the default setup of pretty much everything
 these days.
 
-Share-level security: The anonymous account should be used to log in, then 
+Share-level authentication: The anonymous account should be used to log in, then 
 the password is given (in plaintext) when a share is accessed. All users who
 have access to the share use this password. This was the original way of doing
 things, but isn't commonly seen, now. If a server uses share-level security, 
 it is vulnerable to sniffing.
 
-Challenge/response passwords: If enabled, the server can accept any type of
+Challenge/response passwords supported: If enabled, the server can accept any type of
 password:
-
 * Plaintext
 * LM and NTLM
 * LMv2 and NTLMv2
-
 If it isn't set, the server can only accept plaintext passwords. Most servers
 are configured to use challenge/response these days. If a server is configured
 to accept plaintext passwords, it is vulnerable to sniffing. LM and NTLM are
-fairly secure, although there are some bruteforce attacks against them. 
+fairly secure, although there are some brute-force attacks against them. 
 
 Message signing: If required, all messages between the client and server must
-sign be signed by a shared key, derived from the password and the server
+be signed by a shared key, derived from the password and the server
 challenge. If supported and not required, message signing is negotiated between
 clients and servers and used if both support and request it. By default,
 Windows clients don't sign messages, so if message signing isn't required by
@@ -36,11 +34,10 @@ man-in-the-middle attack, an attacker can negotiate no message signing. If
 message signing isn't required, the server is vulnerable to man-in-the-middle
 attacks.
 
-See nselib/smb.lua for more information on the protocol itself.
+This script will allow you to use the <code>smb*</code> script arguments (to
-
+set the username and password, etc.), but it probably won't ever require them. 
-This script will allow you to use smb arguments (username/password), but it probably
-won't ever require them. 
 ]]
+
 ---
 --@usage
 -- nmap --script smb-security-mode.nse -p445 127.0.0.1
@@ -51,35 +48,33 @@ won't ever require them.
 -- |  SMB Security: Challenge/response passwords supported
 -- |_ SMB Security: Message signing supported
 -- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 author = "Ron Bowes"
@@ -88,7 +83,7 @@ categories = {"discovery", "safe"}
 
 require 'smb'
 
---- Check whether or not this script should be run.
+-- Check whether or not this script should be run.
 hostrule = function(host)
 
 	local port = smb.get_port(host)

scripts/smb-serverstats.nse

@@ -1,9 +1,9 @@
 id = "MSRPC: Server statistics"
 description = [[
-Attempts to grab the server's statistics over SMB + MSRPC, which uses TCP
+Attempts to grab the server's statistics over SMB and MSRPC, which uses TCP
 ports 445 or 139. 
 
-An administrative account is required to pull these statistics on most versions
+An administrator account is required to pull these statistics on most versions
 of Windows, and Vista doesn't seem to let even the administrator account pull them.
 
 Some of the numbers returned here don't feel right to me, but they're definitely 
@@ -24,36 +24,34 @@ the numbers that Windows returns. Take the values here with a grain of salt.
 -- |  |_ Permission errors: 1, System errors: 0
 -- |  |_ Print jobs spooled: 0
 -- |_ |_ Files opened (including pipes): 18
---
+-- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 author = "Ron Bowes"

scripts/smb-systeminfo.nse

@@ -9,6 +9,7 @@ This goes for all operating systems, including Windows 2000.
 Windows Vista doesn't appear to have the WINREG binding (or it's different and
 I don't know it), so this doesn't support Vista at all. 
 ]]
+
 ---
 -- @usage
 -- nmap --script smb-systeminfo.nse -p445 <host>
@@ -37,36 +38,34 @@ I don't know it), so this doesn't support Vista at all.
 -- |  Browsers
 -- |  |_ Internet Explorer 7.0000
 -- |_ |_ Firefox 3.0.3 (en-US)
---
+-- 
---@args  smbusername The SMB username to log in with. The form DOMAIN\username and username@DOMAIN
+--@args  smbusername The SMB username to log in with. The forms "DOMAIN\username" and "username@DOMAIN"
---                   are NOT understood. To set a domain, use the smbdomain argument. 
+--                   are not understood. To set a domain, use the <code>smbdomain</code> argument. 
 --@args  smbdomain   The domain to log in with. If you aren't in a domained environment, then anything
 --                   will (should?) be accepted by the server. 
 --@args  smbpassword The password to connect with. Be cautious with this, since some servers will lock
---                   accounts if the incorrect password is given (although it's rare for the 
+--                   accounts if the incorrect password is given. Although it's rare that the
---                   'administrator' account to be lockoutable, in the off chance that it is, you could
+--                   Administrator account can be locked out, in the off chance that it can, you could
---                   get yourself in trouble). 
+--                   get yourself in trouble. 
 --@args  smbhash     A password hash to use when logging in. This is given as a single hex string (32
---                   characters) or a pair of hex strings (2 x 32 characters, optionally separated by a 
+--                   characters) or a pair of hex strings (both 32 characters, optionally separated by a 
---                   single character). These hashes are the Lanman or NTLM hash of the user's password,
+--                   single character). These hashes are the LanMan or NTLM hash of the user's password,
---                   and are stored by systems, on the harddrive or memory. They can be retrived from memory
+--                   and are stored on disk or in memory. They can be retrieved from memory
 --                   using the fgdump or pwdump tools. 
---@args  smbguest    If this is set to 'true' or '1', a 'guest' login will be attempted if the normal one 
+--@args  smbguest    If this is set to <code>true</code> or <code>1</code>, a guest login will be attempted if the normal one 
 --                   fails. This should be harmless, but I thought I would disable it by default anyway
 --                   because I'm not entirely sure of any possible consequences. 
---@args  smbtype     The type of SMB authentication to use. By default, NTLMv1 is used, which is a pretty
+--@args  smbtype     The type of SMB authentication to use. These are the possible options:
+-- * <code>v1</code>: Sends LMv1 and NTLMv1.
+-- * <code>LMv1</code>: Sends LMv1 only.
+-- * <code>NTLMv1</code>: Sends NTLMv1 only (default).
+-- * <code>v2</code>: Sends LMv2 and NTLMv2.
+-- * <code>LMv2</code>: Sends LMv2 only.
+--                   The default, <code>NTLMv1</code>, is a pretty
 --                   decent compromise between security and compatibility. If you are paranoid, you might 
---                   want to use 'v2' or 'lmv2' for this (actually, if you're paranoid, you should be 
+--                   want to use <code>v2</code> or <code>lmv2</code> for this. (Actually, if you're paranoid, you should be 
 --                   avoiding this protocol altogether :P). If you're using an extremely old system, you 
---                   might need to set this to 'v1' or 'lm', which are less secure but more compatible. 
+--                   might need to set this to <code>v1</code> or <code>lm</code>, which are less secure but more compatible. 
---
---                   If you want finer grained control, these are the possible options:
---                       * v1 -- Sends LMv1 and NTLMv1
---                       * LMv1 -- Sends LMv1 only
---                       * NTLMv1 -- Sends NTLMv1 only (default)
---                       * v2 -- Sends LMv2 and NTLMv2
---                       * LMv2 -- Sends LMv2 only
---
 -----------------------------------------------------------------------
 
 
@@ -94,10 +93,11 @@ end
 
 ---Retrieves the requested value from the registry. 
 --@param smbstate The SMB table we're using, bound to the WINREG service. 
---@param handle   The handle to the hive (HKLM or HKU, for example)
+--@param handle   The handle to the hive (HKLM or HKU, for example).
---@param key      The full path of the key to retrieve (like "SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment")
+--@param key      The full path of the key to retrieve (like <code>"SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"</code>).
---@param value    The value to retrieve (like, "NUMBER_OF_PROCESSORS")
+--@param value    The value to retrieve (like <code>"NUMBER_OF_PROCESSORS"</code>).
---@return (status, result) If status is false, result is an error message. Otherwise, result is the value of the key. 
+--@return Status (true or false).
+--@return The value (if status is true) or an error string (if status is false).
 local function reg_get_value(smbstate, handle, key, value)
 
 	-- Open the key