Land #8 - Fix style and yardoc from @jlee-r7

Author: OJ

lib/rex/post/meterpreter/extensions/kiwi/kiwi.rb

@@ -39,7 +39,7 @@ class Kiwi < Extension
   # dumped kerberos tickets. The order of these is important. Each
   # of them was pulled from the Mimikatz 2.0 source base.
   #
-  @@kerberos_flags = [
+  KERBEROS_FLAGS = [
     "NAME CANONICALIZE",
     "<unknown>",
     "OK AS DELEGATE",
@@ -56,11 +56,12 @@ class Kiwi < Extension
     "FORWARDED",
     "FORWARDABLE",
     "RESERVED"
-  ]
+  ].map(&:freeze).freeze
 
   #
   # Typical extension initialization routine.
   #
+  # @param client (see Extension#initialize)
   def initialize(client)
     super(client, 'kiwi')
 
@@ -76,8 +77,7 @@ def initialize(client)
   #
   # Dump the LSA secrets from the target machine.
   #
-  # Returns [Hash]
-  #
+  # @return [Hash<Symbol,Object>]
   def lsa_dump
     request = Packet.create_request('kiwi_lsa_dump_secrets')
 
@@ -129,17 +129,15 @@ def lsa_dump
   # Convert a flag set to a list of string representations for the bit flags
   # that are set.
   #
-  # @param flags [Integer] - Integer bitmask of Kerberos token flags.
-  #
-  # Returns [String]
+  # @param flags [Fixnum] Integer bitmask of Kerberos token flags.
   #
+  # @return [Array<String>] Names of all set flags in +flags+. See
+  #   {KERBEROS_FLAGS}
   def to_kerberos_flag_list(flags)
     flags = flags >> 16
     results = []
 
-    @@kerberos_flags.each_with_index do |item, idx|
-      mask = 1 << idx
-
+    KERBEROS_FLAGS.each_with_index do |item, idx|
       if (flags & (1 << idx)) != 0
         results  << item
       end
@@ -151,9 +149,9 @@ def to_kerberos_flag_list(flags)
   #
   # List available kerberos tickets.
   #
-  # @param export [Bool] - Set to +true+ to export the content of each ticket
+  # @param export [Bool] Set to +true+ to export the content of each ticket
   #
-  # Returns [Array[Hash]]
+  # @return [Array<Hash>]
   #
   def kerberos_ticket_list(export)
     export ||= false
@@ -184,9 +182,9 @@ def kerberos_ticket_list(export)
   #
   # Use the given ticket in the current session.
   #
-  # @param icket [Array[Byte]] - Content of the Kerberos ticket to use.
+  # @param ticket [String] Content of the Kerberos ticket to use.
   #
-  # Returns [Bool]
+  # @return [void]
   #
   def kerberos_ticket_use(ticket)
     request = Packet.create_request('kiwi_kerberos_ticket_use')
@@ -198,7 +196,7 @@ def kerberos_ticket_use(ticket)
   #
   # Purge any Kerberos tickets that have been added to the current session.
   #
-  # Returns [Bool]
+  # @return [void]
   #
   def kerberos_ticket_purge
     request = Packet.create_request('kiwi_kerberos_ticket_purge')
@@ -209,14 +207,14 @@ def kerberos_ticket_purge
   #
   # Create a new golden kerberos ticket on the target machine and return it.
   #
-  # @param user [String] - Name of the user to create the ticket for.
-  # @param domain [String] - Domain name.
-  # @param sid [String] - SID of the domain.
-  # @param tgt [String] - The kerberos ticket granting token.
-  # @param id [Integer] - ID of the user to grant the token for.
-  # @param group_ids [Array[Integer]] - IDs of the groups to assign to the user
+  # @param user [String] Name of the user to create the ticket for.
+  # @param domain [String] Domain name.
+  # @param sid [String] SID of the domain.
+  # @param tgt [String] The kerberos ticket granting token.
+  # @param id [Fixnum] ID of the user to grant the token for.
+  # @param group_ids [Array<Fixnum>] IDs of the groups to assign to the user
   #
-  # Returns [Array[Byte]]
+  # @return [String]
   #
   def golden_ticket_create(user, domain, sid, tgt, id = 0, group_ids = [])
     request = Packet.create_request('kiwi_kerberos_golden_ticket_create')
@@ -231,15 +229,14 @@ def golden_ticket_create(user, domain, sid, tgt, id = 0, group_ids = [])
     end
 
     response = client.send_request(request)
-return response.get_tlv_value(TLV_TYPE_KIWI_KERB_TKT_RAW)
+    return response.get_tlv_value(TLV_TYPE_KIWI_KERB_TKT_RAW)
   end
 
   #
   # List all the wifi interfaces and the profiles associated
   # with them. Also show the raw text passwords for each.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return [Array<Hash>]
   def wifi_list
     request = Packet.create_request('kiwi_wifi_profile_list')
 
@@ -278,10 +275,9 @@ def wifi_list
   #
   # Scrape passwords from the target machine.
   #
-  # @param pwd_id - ID of the type credential to scrape.
-  #
-  # Returns [Array[Hash]]
+  # @param pwd_id [Fixnum] ID of the type credential to scrape.
   #
+  # @return [Array<Hash>]
   def scrape_passwords(pwd_id)
     request = Packet.create_request('kiwi_scrape_passwords')
     request.add_tlv(TLV_TYPE_KIWI_PWD_ID, pwd_id)
@@ -306,62 +302,55 @@ def scrape_passwords(pwd_id)
   #
   # Scrape all passwords from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def all_pass
     scrape_passwords(PWD_ID_SEK_ALLPASS)
   end
 
   #
   # Scrape wdigest credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def wdigest
     scrape_passwords(PWD_ID_SEK_WDIGEST)
   end
 
   #
   # Scrape msv credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def msv
     scrape_passwords(PWD_ID_SEK_MSV)
   end
 
   #
   # Scrape LiveSSP credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def livessp
     scrape_passwords(PWD_ID_SEK_LIVESSP)
   end
 
   #
   # Scrape SSP credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def ssp
     scrape_passwords(PWD_ID_SEK_SSP)
   end
 
   #
   # Scrape TSPKG credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def tspkg
     scrape_passwords(PWD_ID_SEK_TSPKG)
   end
 
   #
   # Scrape Kerberos credentials from the target machine.
   #
-  # Returns [Array[Hash]]
-  #
+  # @return (see #scrape_passwords)
   def kerberos
     scrape_passwords(PWD_ID_SEK_KERBEROS)
   end

lib/rex/post/meterpreter/ui/console/command_dispatcher/kiwi.rb

@@ -433,10 +433,10 @@ def cmd_creds_kerberos(*args)
 protected
 
   def check_privs
-    unless system_check
-      print_warning("Not running as SYSTEM, execution may fail")
-    else
+    if system_check
       print_good("Running as SYSTEM")
+    else
+      print_warning("Not running as SYSTEM, execution may fail")
     end
   end
 
@@ -452,11 +452,13 @@ def system_check
   #
   # Invoke the password scraping routine on the target.
   #
-  # +provider+ [String] - The name of the type of credentials to dump (used for
-  #   display purposes only).
-  # +method+ [Block] - Block that contains a call to the method that invokes the
-  #   appropriate function on the client that returns the results from Meterpreter.
+  # @param provider [String] The name of the type of credentials to dump
+  #   (used for display purposes only).
+  # @param method [Proc] Block that calls the method that invokes the
+  #   appropriate function on the client that returns the results from
+  #   Meterpreter that lay in the house that Jack built.
   #
+  # @return [void]
   def scrape_passwords(provider, method)
     check_privs
     print_status("Retrieving #{provider} credentials")
@@ -488,12 +490,14 @@ def scrape_passwords(provider, method)
   end
 
   #
-  # Helper function to convert a potentially blank value to hex and have the
-  #   outer spaces stripped
+  # Helper function to convert a potentially blank value to hex and have
+  # the outer spaces stripped
   #
+  # @param (see Rex::Text.to_hex)
+  # @return [String] The result of {Rex::Text.to_hex}, strip'd
   def to_hex(value, sep = '')
     value ||= ""
-    Rex::Text::to_hex(value, sep).strip
+    Rex::Text.to_hex(value, sep).strip
   end
 
 end

lib/rex/text.rb

@@ -1291,13 +1291,16 @@ def self.rand_guid
   end
 
   #
-  # Convert an array of 16 bytes to a GUID string
+  # Convert 16-byte string to a GUID string
   #
-  # @param bytes [Array[Byte]] Array of 16 bytes which represent a GUID
-  #   in the proper order.
+  # @example
+  #   str = "ABCDEFGHIJKLMNOP"
+  #   Rex::Text.to_guid(str) #=> "{44434241-4645-4847-494a-4b4c4d4e4f50}"
   #
-  # Returns [String].
+  # @param bytes [String] 16 bytes which represent a GUID in the proper
+  #   order.
   #
+  # @return [String]
   def self.to_guid(bytes)
     return nil unless bytes
     s = bytes.unpack('H*')[0]