hivexcavator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4d06b0b8f7b2af64065f2a63ff500e8c16ea41506dbc2c86dbde98f021be81d
+  data.tar.gz: b5136b478c400a20b4faf68efc018dbfdff2f409e862ca2b32bee9b80b7a203c
+SHA512:
+  metadata.gz: abaefd8f2fb7e29972a32321f11bc9e764fdf983f7249950b954fee80882efffc1af6c657f08ab4386fa887a3888ae2a26397b7187a468d1c8869148e3aa7858
+  data.tar.gz: 23d7f34c90a3d8465de1bbea763ed9b029e95ce9abb66f9068f58ef272509bb498d16c3747fbd0d947910e5d08b226104bbbb693b4af86101d3ac5c5de202f04

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Alexandre ZANNI at ACCEIS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/bin/hivexcavator

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Internal
+require 'hivexcavator'
+require 'hivexcavator/cli'
+
+HivExcavator::CLI

data/lib/hivexcavator/cli.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Third party
+require 'docopt'
+require 'paint'
+
+class HivExcavator
+  # module used for the CLI binary only, not required by the library
+  module CLI
+    pal = HivExcavator::PALETTE
+
+    doc = <<~DOCOPT
+      #{Paint['HivExcavator', :bold, pal[:MAIN]]} version #{Paint[HivExcavator::VERSION, :bold, pal[:THIRD]]}
+
+      #{Paint['Usage:', pal[:SECOND]]}
+        #{Paint['hivexcavator', pal[:THIRD]]} [options] <bcd>
+
+      #{Paint['Parameters:', pal[:SECOND]]}
+        #{Paint['<bcd>', pal[:FOURTH]]}           BCD file
+
+      #{Paint['Options:', pal[:SECOND]]}
+        #{Paint['--no-color', pal[:FOURTH]]}      Disable colorized output (NO_COLOR environment variable is respected too)
+        #{Paint['--debug', pal[:FOURTH]]}         Display arguments
+        #{Paint['-h', pal[:FOURTH]]}, #{Paint['--help', pal[:FOURTH]]}      Show this screen
+        #{Paint['--version', pal[:FOURTH]]}       Show version
+
+      #{Paint['Examples:', pal[:SECOND]]}
+        hivexcavator ~/test/pxe/conf.bcd
+
+      #{Paint['Project:', pal[:SECOND]]}
+        #{Paint['author', :underline]} (https://pwn.by/noraj / https://twitter.com/noraj_rawsec)
+        #{Paint['source', :underline]} (https://github.com/acceis/hivexcavator)
+        #{Paint['documentation', :underline]} (https://acceis.github.io/hivexcavator)
+    DOCOPT
+
+    begin
+      args = Docopt.docopt(doc, version: HivExcavator::VERSION)
+      Paint.mode = 0 if args['--no-color']
+      puts args if args['--debug']
+      if args['<bcd>']
+        hiex = HivExcavator.new(args['<bcd>'])
+        hiex.display
+      end
+    rescue Docopt::Exit => e
+      puts e.message
+    end
+  end
+end

data/lib/hivexcavator/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class HivExcavator
+  # Version of HivExcavator library and app
+  VERSION = '0.0.1'
+end

data/lib/hivexcavator.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# Internal
+require 'hivexcavator/version'
+# Third party
+require 'hivex'
+require 'paint'
+
+# Extracting the contents of Microsoft Windows Registry (hive) and display it as a colorful tree but mainly focused on
+# parsing BCD files to extract WIM files path for PXE attacks.
+class HivExcavator
+  # Windows Registry Value Type
+  # @see https://learn.microsoft.com/en-us/dotnet/api/microsoft.win32.registryvaluekind?view=net-7.0
+  TYPE = {
+    -1 => 'none',
+    0 => 'unknown',
+    1 => 'string',
+    2 => 'expandstring',
+    3 => 'binary',
+    4 => 'dword', # hex
+    7 => 'multistring',
+    11 => 'qword' # hex
+  }.freeze
+
+  # Color palette of HivExcavator for display
+  PALETTE = {
+    MAIN: '#fe218b', # 70d6ff
+    SECOND: '#fed700', # ff70a6
+    THIRD: '#21b0fe', # ff9770
+    FOURTH: '#06d6a0' # ffd670
+  }.freeze
+
+  # Instantiate HivExcavator
+  # @param hive [String|Hivex::Hivex] Can be either a file path to a BCD file +String+ or a Hivex (hive)
+  #   instance +Hivex::Hivex+.
+  def initialize(hive)
+    case hive
+    when Hivex::Hivex
+      @hive = hive
+    when String
+      @hive = Hivex.open(hive, {})
+    end
+  end
+
+  # Does a node has children?
+  # @param hive [Hivex::Hivex] hive instance
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def self.node_children?(hive, node)
+    !hive.node_children(node).empty?
+  end
+
+  # Does a node has children?
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def node_children?(node)
+    HivExcavator.node_children?(@hive, node)
+  end
+
+  # Does a node has a parent?
+  # @param hive [Hivex::Hivex] hive instance
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def self.node_parent?(hive, node)
+    hive.node_parent(node).integer?
+  rescue Hivex::Error # Bad address
+    false
+  end
+
+  # Does a node has a parent?
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def node_parent?(node)
+    HivExcavator.node_parent?(@hive, node)
+  end
+
+  # Does a node has values?
+  # @param hive [Hivex::Hivex] hive instance
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def self.node_values?(hive, node)
+    !hive.node_values(node).empty?
+  end
+
+  # Does a node has values?
+  # @param node [Integer] node index
+  # @return [Boolean]
+  def node_values?(node)
+    HivExcavator.node_values?(@hive, node)
+  end
+
+  # Calculate the depth (nesting level) of a node (from the root node)
+  # @param hive [Hivex::Hivex] hive instance
+  # @param node [Integer] node index
+  # @return [Integer] depth level
+  def self.node_depth(hive, node)
+    count = 0
+    parent = node
+    while node_parent?(hive, parent)
+      parent = hive.node_parent(parent)
+      count += 1
+    end
+    count
+  end
+
+  # Calculate the depth (nesting level) of a node (from the root node)
+  # @param node [Integer] node index
+  # @return [Integer] depth level
+  def node_depth(node)
+    HivExcavator.node_depth(@hive, node)
+  end
+
+  # Output a number of whitespace depending on the depth
+  # @param hive [Hivex::Hivex] hive instance
+  # @param node [Integer] node index
+  # @param spaces [Integer] number of whitespaces per level
+  # @return [String] whitespaces
+  def self.space_depth(hive, node, spaces = 2)
+    ' ' * spaces * node_depth(hive, node)
+  end
+
+  # Output a number of whitespace depending on the depth
+  # @param node [Integer] node index
+  # @param spaces [Integer] number of whitespaces per level
+  # @return [String] whitespaces
+  def space_depth(node, spaces = 2)
+    HivExcavator.space_depth(@hive, node, spaces)
+  end
+
+  # Try to resolve known types to extract the value else just fix encoding of the provided value
+  # @param hive [Hivex::Hivex] hive instance
+  # @param value [Integer] value index
+  # @return [String] The decoded value
+  def self.extract_value(hive, value)
+    value_type = TYPE[hive.value_type(value)[:type]]
+    case value_type
+    when 'string'
+      hive.value_string(value)
+    when 'dword'
+      hive.value_dword(value)
+    when 'qword'
+      hive.value_qword(value)
+    else
+      hive.value_value(value)[:value].encode('UTF-8', 'Windows-1252').gsub("\n", '')
+    end
+  end
+
+  # Try to resolve known types to extract the value else just fix encoding of the provided value
+  # @param value [Integer] value index
+  # @return [String] The decoded value
+  def extract_value(value)
+    HivExcavator.extract_value(@hive, value)
+  end
+
+  # Display the BCD file as a tree
+  # @param hive [Hivex::Hivex] hive instance
+  # @param current_node [Integer] node index
+  # @return [nil]
+  def self.node_list(hive, current_node)
+    nodes = hive.node_children(current_node)
+    nodes.each do |node|
+      node_name = hive.node_name(node)
+      puts "#{space_depth(hive, node)}#{Paint[node_name, PALETTE[:MAIN]]} (#{Paint[node, PALETTE[:SECOND]]})"
+      if node_values?(hive, node)
+        node_values = hive.node_values(node)
+        node_values.each do |value|
+          value_value = extract_value(hive, value)
+          print "  #{space_depth(hive, node)}#{Paint[hive.value_key(value), PALETTE[:FOURTH]]} :"
+          puts "#{Paint[value_value, PALETTE[:THIRD]]} (#{Paint[value, PALETTE[:SECOND]]})"
+        end
+      end
+      node_list(hive, node) if node_children?(hive, node)
+    end
+    nil
+  end
+
+  # Display the BCD file as a tree
+  # @param current_node [Integer] node index
+  # @return [nil]
+  def node_list(current_node)
+    HivExcavator.node_list(@hive, current_node)
+  end
+
+  # Display a line with the name of the store / hive
+  # @param hive [Hivex::Hivex] hive instance
+  # @return [nil]
+  def self.diplay_store(hive)
+    root = hive.root
+    puts "#{Paint[hive.node_name(root), PALETTE[:MAIN]]} (#{Paint[root, PALETTE[:SECOND]]})"
+  end
+
+  # Display a line with the name of the store / hive
+  # @return [nil]
+  def diplay_store
+    HivExcavator.diplay_store(@hive)
+  end
+
+  # Display the tree of all nodes, key and values
+  # @param hive [Hivex::Hivex] hive instance
+  # @return [nil]
+  def self.display_tree(hive)
+    node_list(hive, hive.root)
+  end
+
+  # Display the tree of all nodes, key and values
+  # @return [nil]
+  def display_tree
+    HivExcavator.display_tree(@hive)
+  end
+
+  # Display the store name ({diplay_store}) and the tree ({display_tree})
+  # @param hive [Hivex::Hivex] hive instance
+  # @return [nil]
+  # @example
+  #   require 'hivexcavator'
+  #   require 'hivex'
+  #
+  #   store = Hivex.open('/home/noraj/test/pxe/conf.bcd', {})
+  #   HivExcavator.display(store)
+  #   store.close
+  def self.display(hive)
+    diplay_store(hive)
+    display_tree(hive)
+  end
+
+  # Display the store name ({diplay_store}) and the tree ({display_tree})
+  # @return [nil]
+  # @example
+  #   require 'hivexcavator'
+  #   require 'hivex'
+  #
+  #   store = '/home/noraj/test/pxe/conf.bcd'
+  #   hiex = HivExcavator.new(store)
+  #   hiex.display
+  def display
+    HivExcavator.display(@hive)
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: hivexcavator
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexandre ZANNI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: docopt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Extracting the contents of Microsoft Windows Registry (hive) and display
+  it as a colorful tree but mainly focused on parsing BCD files to extract WIM files
+  path for PXE attacks.
+email: alexandre.zanni@europe.com
+executables:
+- hivexcavator
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- bin/hivexcavator
+- lib/hivexcavator.rb
+- lib/hivexcavator/cli.rb
+- lib/hivexcavator/version.rb
+homepage: https://acceis.github.io/hivexcavator/
+licenses:
+- MIT
+metadata:
+  yard.run: yard
+  bug_tracker_uri: https://github.com/acceis/hivexcavator/issues
+  changelog_uri: https://github.com/acceis/hivexcavator/blob/master/docs/CHANGELOG.md
+  documentation_uri: https://acceis.github.io/hivexcavator/
+  homepage_uri: https://acceis.github.io/hivexcavator/
+  source_code_uri: https://github.com/acceis/hivexcavator/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.25
+signing_key:
+specification_version: 4
+summary: Parse BCD files to extract WIM files path (among other stuff)
+test_files: []