metasploit-gs/lib/msf/util/windows_registry/registry_parser.rb

module Msf
module Util
module WindowsRegistry

  #
  # This utility class processes binary Windows registry key. It is usually
  # used when only offline processing is possible and [MS-RRP] BaseRegSaveKey()
  # is used to save a registry key to a file.
  #
  # It also includes helpers for specific registry keys (SAM, SECURITY) through
  # the `name` key word argument during instantiation.
  #
  class RegistryParser
    # Constants
    ROOT_KEY        = 0x2c
    REG_NONE        = 0x00
    REG_SZ          = 0x01
    REG_EXPAND_SZ   = 0x02
    REG_BINARY      = 0x03
    REG_DWORD       = 0x04
    REG_MULTISZ     = 0x07
    REG_QWORD       = 0x0b


    # Magic strings

    # REGF magic value: 'regf'
    REGF_MAGIC = 0x72656766
    # NK magic value: 'nk'
    NK_MAGIC = 0x6E6B
    # VK magic value: 'vk'
    VK_MAGIC = 0x766B
    # LF magic value: 'lf'
    LF_MAGIC = 0x6C66
    # LH magic value: 'lh'
    LH_MAGIC = 0x6C68
    # RI magic value: 'ri'
    RI_MAGIC = 0x7269
    # SK magic value: 'sk'
    SK_MAGIC = 0x7269
    # HBIN magic value: 'hbin'
    HBIN_MAGIC = 0x6862696E

    #
    # [Windows NT Registry File (REGF) format specification](https://github.com/libyal/libregf/blob/main/documentation/Windows%20NT%20Registry%20File%20(REGF)%20format.asciidoc)
    #

    # Registry File Header
    class RegRegf < BinData::Record
      endian :little

      bit32  :magic, initial_value: REGF_MAGIC
      uint32 :sequence1
      uint32 :sequence2
      uint64 :last_change
      uint32 :major_version
      uint32 :minor_version
      uint32 :unknown1
      uint32 :unknown2
      uint32 :offset_first_record
      uint32 :data_size
      uint32 :unknown3
      string :name, length: 48
      string :remaining1, length: 411
      uint32 :checksum, initial_value: 0xFFFFFFFF
      string :remaining2, length: 3585
    end

    # Named key
    class RegNk < BinData::Record
      endian :little

      bit16  :magic, initial_value: NK_MAGIC
      uint16 :nk_type
      uint64 :last_change
      uint32 :unknown
      int32  :offset_parent
      uint32 :num_sub_keys
      uint32 :unknown2
      int32  :offset_sub_key_lf
      uint32 :unknown3
      uint32 :num_values
      int32  :offset_value_list
      int32  :offset_sk_rRecord
      int32  :offset_class_name
      string :unused, length: 20
      uint16 :name_length, initial_value: -> { self.key_name.length }
      uint16 :class_name_length
      string :key_name, read_length: -> { self.name_length }
    end

    # Value key
    class RegVk < BinData::Record
      endian :little

      bit16  :magic, initial_value: VK_MAGIC
      uint16 :name_length, initial_value: -> { self.name.length }
      int32  :data_len
      uint32 :offset_data
      uint32 :value_type
      uint16 :flag
      uint16 :unused
      string :name, read_length: -> { self.name_length }
    end

    class RegHash < BinData::Record
      endian :little

      int32  :offset_nk
      string :key_name, length: 4
    end

    class RegHash2 < BinData::Record
      endian :little

      int32  :offset_nk
    end

    # Sub keys list (LF)
    class RegLf < BinData::Record
      endian :little

      bit16  :magic, initial_value: LF_MAGIC
      uint16 :num_keys
      array  :hash_records, type: :reg_hash, read_until: -> { index == (self.num_keys - 1) }
    end

    # Sub keys list (LH)
    class RegLh < BinData::Record
      endian :little

      bit16  :magic, initial_value: LH_MAGIC
      uint16 :num_keys
      array  :hash_records, type: :reg_hash, read_until: -> { index == (self.num_keys - 1) }
    end

    # Sub keys list (RI)
    class RegRi < BinData::Record
      endian :little

      bit16  :magic, initial_value: RI_MAGIC
      uint16 :num_keys
      array  :hash_records, type: :reg_hash2, read_until: -> { index == (self.num_keys - 1) }
    end

    # Security key
    class RegSk < BinData::Record
      endian :little

      bit16  :magic, initial_value: SK_MAGIC
      uint16 :unused
      int32  :offset_previous_sk
      int32  :offset_next_sk
      uint32 :usage_counter
      uint32 :size_sk, initial_length: -> { self.data.do_num_bytes }
      string :data, read_length: -> { self.size_sk }
    end

    # Hive bin cell
    class RegHbinBlock < BinData::Record
      attr_reader :record_type

      endian :little

      int32  :data_block_size#, byte_align: 4
      choice :data, selection: -> { @obj.parent.record_type } do
        reg_nk 'nk'
        reg_vk 'vk'
        reg_lf 'lf'
        reg_lh 'lh'
        reg_ri 'ri'
        reg_sk 'sk'
        string :default, read_length: -> { self.data_block_size == 0 ? 0 : self.data_block_size.abs - 4 }
      end
      string :unknown, length: -> { self.data_block_size.abs - self.data.do_num_bytes - 4 }

      def do_read(io)
        io.with_readahead do
          io.seekbytes(4)
          @record_type = io.readbytes(2)
        end
        super(io)
      end
    end

    # Hive bin
    class RegHbin < BinData::Record
      endian :little

      bit32  :magic, initial_value: HBIN_MAGIC
      uint32 :offset_first_hbin
      uint32 :hbin_size
      string :unknown, length: 16
      uint32 :offset_next_hbin # hbin_size
      array  :reg_hbin_blocks, type: :reg_hbin_block, read_until: :eof
    end


    # @param hive_data [String] The binary registry data
    # @param name [Symbol] The key name to add specific helpers. Only `:sam`
    #   and `:security` are supported at the moment.
    def initialize(hive_data, name: nil)
      @hive_data = hive_data.b
      @regf = RegRegf.read(@hive_data)
      @root_key = find_root_key
      case name
      when :sam
        require_relative 'sam'
        extend Sam
      when :security
        require_relative 'security'
        extend Security
      end
    end

    # Returns the ROOT key as a block
    #
    # @return [RegHbinBlock] The ROOT key block
    # @raise [StandardError] If an error occurs during parsing or if the ROOT
    #   key is not found
    def find_root_key
      reg_hbin = nil
      # Split the data in 4096-bytes blocks
      @hive_data.unpack('a4096' * (@hive_data.size / 4096)).each do |data|
        next unless data[0,4] == 'hbin'
        reg_hbin = RegHbin.read(data)
        root_key = reg_hbin.reg_hbin_blocks.find do |block|
          block.data.respond_to?(:magic) && block.data.magic == NK_MAGIC && block.data.nk_type == ROOT_KEY
        end
        return root_key if root_key
      rescue IOError
        raise StandardError, 'Cannot parse the RegHbin structure'
      end
      raise StandardError, 'Cannot find the RootKey' unless reg_hbin
    end

    # Returns the type and the data of a given key/value pair
    #
    # @param reg_key [String] The registry key
    # @param reg_value [String] The value in the registry key
    # @return [Array] The type (Integer) and data (String) of the given
    #   key/value as the first and second element of an array, respectively
    def get_value(reg_key, reg_value = nil)
      reg_key = find_key(reg_key)
      return nil unless reg_key

      if reg_key.data.num_values > 0
        value_list = get_value_blocks(reg_key.data.offset_value_list, reg_key.data.num_values + 1)
        value_list.each do |value|
          if value.data.name == reg_value.to_s ||
             reg_value.nil? && value.data.flag <= 0
            return value.data.value_type.to_i, get_value_data(value.data)
          end
        end
      end
      nil
    end

    # Search for a given key from the ROOT key and returns it as a block
    #
    # @param key [String] The registry key to look for
    # @return [RegHbinBlock, nil] The key, if found, nil otherwise
    def find_key(key)
      # Let's strip '\' from the beginning, except for the case of
      # only asking for the root node
      key = key[1..-1] if key[0] == '\\' && key.size > 1

      parent_key = @root_key
      if key.size > 0 && key[0] != '\\'
        key.split('\\').each do |sub_key|
          res = find_sub_key(parent_key, sub_key)
          return nil unless res
          parent_key = res
        end
      end
      parent_key
    end

    # Search for a sub key from a given base key
    #
    # @param parent_key [String] The base key
    # @param sub_key [String] The sub key to look for under parent_key
    # @return [RegHbinBlock, nil] The key, if found, nil otherwise
    # @raise [ArgumentError] If the parent key is not a NK record
    def find_sub_key(parent_key, sub_key)
      unless parent_key&.data&.magic == NK_MAGIC
        raise ArgumentError, "find_sub_key: parent key must be a NK record"
      end
      block = get_block(parent_key.data.offset_sub_key_lf)
      blocks = []
      if block.data.magic == RI_MAGIC
        # ri points to lf/lh records, so we consolidate them in the main blocks array
        block.data.hash_records.each do |hash_record|
          blocks << get_block(hash_record.offset_nk)
        end
      else
        blocks << block
      end

      # Let's search the hash records for the name
      blocks.each do |block|
        block.data.hash_records.each do |hash_record|
          res = get_offset(block.data.magic, hash_record, sub_key)
          if res
            nk = get_block(res)
            return nk if nk.data.key_name == sub_key
          end
        end
      end

      nil
    end

    # Returns a registry block given its offset
    #
    # @param offset [String] The offset of the block
    # @return [RegHbinBlock] The registry block
    def get_block(offset)
      RegHbinBlock.read(@hive_data[4096+offset..-1])
    end

    # Returns the offset of a given subkey in a hash record
    #
    # @param magic [Integer] The signtaure (MAGIC)
    # @param hash_rec [Integer] The hash record
    # @param key [Integer] The subkey to look for
    # @return [Integer] The offset of the subkey
    def get_offset(magic, hash_rec, key)
      case magic
      when LF_MAGIC
        if hash_rec.key_name.gsub(/(^\x00*)|(\x00*$)/, '') == key[0,4]
          return hash_rec.offset_nk
        end
      when LH_MAGIC
        if hash_rec.key_name.unpack('L<').first == get_lh_hash(key)
          return hash_rec.offset_nk
        end
      when RI_MAGIC
        # Special case here, don't know exactly why, an RI pointing to a NK
        offset = hash_rec.offset_nk
        nk = get_block(offset)
        return offset if nk.key_name == key
      else
        raise ArgumentError, "Unknown magic: #{magic}"
      end
    end

    # Returns the hash of a LH subkey
    # from http://www.sentinelchicken.com/data/TheWindowsNTRegistryFileFormat.pdf (Appendix C)
    #
    # @param key [Integer] The LH subkey
    # @return [Integer] The hash
    def get_lh_hash(key)
      res = 0
      key.upcase.bytes do |byte|
        res *= 37
        res += byte.ord
      end
      return res % 0x100000000
    end

    # Returns a list of `count``value blocks from the offsets located at `offset`
    #
    # @param offset [Integer] The offset where the offsets of each value is located
    # @param count [Integer] The number of value blocks to retrieve
    # @return [Array] An array of registry blocks
    def get_value_blocks(offset, count)
      value_list = []
      res = []
      count.times do |i|
        value_list << @hive_data[4096+offset+i*4, 4].unpack('l<').first
      end
      value_list.each do |value_offset|
        if value_offset > 0
          block = get_block(value_offset)
          res << block
        end
      end
      return res
    end

    # Returns the data of a VK record value
    #
    # @param record [String] The VK record
    # @return [String] The data
    # @raise [ArgumentError] If the parent key is not a VK record
    def get_value_data(record)
      unless record&.magic == VK_MAGIC
        raise ArgumentError, "get_value_data: record must be a VK record"
      end
      return '' if record.data_len == 0
      # if DataLen < 5 the value itself is stored in the Offset field
      return record.offset_data.to_binary_s if record.data_len < 0
      return self.get_data(record.offset_data, record.data_len + 4)
    end

    # Returns the data at a given offset from the end of the header in the raw
    # hive binary.
    #
    # @param offset [String] The offset from the end of the header
    # @param count [Integer] The size of the data. Since the 4 first bytes are
    #   ignored, the data returned will be (count - 4) long.
    # @return [String] The resulting data
    def get_data(offset, count)
      @hive_data[4096+offset, count][4..-1]
    end

    # Enumerate the subkey names under `key`
    #
    # @param key [String] The parent key from which to enumerate
    # @return [Array] The key names
    # @raise [ArgumentError] If the parent key is not a NK record
    def enum_key(key)
      parent_key = find_key(key)
      return nil unless parent_key

      unless parent_key.data&.magic == NK_MAGIC
        raise ArgumentError, "enum_key: parent key must be a NK record"
      end
      block = get_block(parent_key.data.offset_sub_key_lf)
      records = []
      if block.data.magic == RI_MAGIC
        # ri points to lf/lh records, so we consolidate the hash records in the main records array
        block.data.hash_records.each do |hash_record|
          record = get_block(hash_record.offset_nk)
          records.concat(record.data.hash_records)
        end
      else
        records.concat(block.data.hash_records)
      end

      records.map do |reg_hash|
        nk = get_block(reg_hash.offset_nk)
        nk.data.key_name.to_s.b
      end
    end

    # Enumerate the subkey values under `key`
    #
    # @param key [String] The parent key from which to enumerate
    # @return [Array] The key values
    # @raise [ArgumentError] If the parent key is not a NK record
    def enum_values(key)
      key_obj = find_key(key)
      return nil unless key_obj

      unless key_obj&.data&.magic == NK_MAGIC
        raise ArgumentError, "enum_values: key must be a NK record"
      end
      res = []
      value_list = get_value_blocks(key_obj.data.offset_value_list, key_obj.data.num_values + 1)
      value_list.each do |value|
        res << (value.data.flag > 0 ? value.data.name : nil)
      end
      res
    end

  end

end
end
end