HoneyClient::Agent::Integrity::Registry::Parser - Perl extension to parse static hive dumps of the Windows OS registry.

This documentation refers to HoneyClient::Agent::Integrity::Registry::Parser version 0.98.

  use HoneyClient::Agent::Integrity::Registry::Parser;
  use IO::File;
  use Data::Dumper;

  # Initialize the parser object.
  my $parser = HoneyClient::Agent::Integrity::Registry::Parser->init(
                   input_file => "dump.reg",
               );

  # Print each registry group found, until there are no more left.
  my $registryGroup = $parser->nextGroup();
  while(scalar(keys(%{$registryGroup}))) {
      print Dumper($registryGroup);
      $registryGroup = $parser->nextGroup();
  }

  # $registryGroup refers to hashtable reference, which has the
  # following format:
  #
  # $registryGroup = {
  #     # The registry directory name.
  #     'key' => 'HKEY_LOCAL_MACHINE\Software...',
  #
  #     # An array containing the list of entries within the
  #     # registry directory.
  #     'entries'  => [ {
  #         'name' => "\"string\"",  # A (potentially) quoted string; 
  #                                  # "@" for default
  #         'value' => "data",
  #     }, ],
  # };

This library allows the Registry module to easily parse and enumerate each Windows OS registry hive.

The following functions have been implemented by any Parser object.

Creates a new Parser object, using the specified input file as its data source.

Inputs:$filename is an required parameter, specifying the file to open for parsing.$perform_index is an optional parameter. 1 specifies that the parser should go ahead and scan the entire file, indexing the file offsets of where groups start and end. Otherwise, this indexing process is not performed.$progress is an optional parameter. 1 specifies that the parser should display a progress bar, as it scans through a specified file. Otherwise, a progress bar is not displayed.

Output: The instantiated Parser $object, fully initialized.

Provides the next registry group, in the form of a hashtable reference. This hashtable has the following format:

  {
      # The registry directory name.
      'key' => 'HKEY_LOCAL_MACHINE\Software...',

      # An array containing the list of entries within the
      # registry directory.
      'entries'  => [ {
          'name' => "\"string\"",  # A (potentially) quoted string; 
                                   # "@" for default
          'value' => "data",
      }, ],
  };

Output: A hashtable reference if the next group was parsed successfully; returns an empty hash ref, if the Parser $object has reached the end of the input stream.

Indicates how many registry directories the Parser $object has parsed within the specified file, so far.

Output: Returns the number of directory groups parsed so far; returns 0, if none parsed yet.

Indicates how many registry key/value pairs the Parser $object has parsed within the specified file, so far.

Output: Returns the number of key/value pairs parsed so far; returns 0, if none parsed yet.

Returns the file handle associated with the current Parser $object.

Output: Returns the file handle in use.

Returns the file name associated with the current Parser $object.

Output: Returns the file name in use.

Closes the file handle associated with the current Parser $object.

Returns the number of lines parsed by the Parser $object within the specified file and resets the counter back to zero.

Output: Returns the current line count of the parser.

Note: Calling this function will reset the parser's line count.

Given an absolute offset or line number within the file, this function will seek the parser to the nearest group found before the specified offset.

Inputs:$offset is an required parameter, specifying the absolute offset within the file to seek to.$linenum is a required parameter, specifying the absolute line number within the file to seek to.$index is an optional parameter, specifying to seek to a group before or after the target group. If unspecified, $index = 0.

Outputs: None.

Notes: Either $offset or $linnum must be specified. To seek to the target group, specify $index = 0 or leave undefined. To seek to the previous group before the target group, specify $index = -1. To seek to the next group after the target group, specify $index = 1.

Once called, all corresponding statistical counters will be reset. This means, that the output from $object->dirsParsed() and $object->entriesParsed() will be zero, if called immediately after this function.

The Parser $object expects to scan the specified file as an input stream. Subsequent calls to $object->nextGroup() will advance the parser through the input stream.

http://www.honeyclient.org/trac

http://www.honeyclient.org/trac/newticket

Francois Desarmenien <francois@fdesar.net> for his work in developing the Parse::Yapp module.

Darien Kindlund, <kindlund@mitre.org>

Copyright (C) 2007 The MITRE Corporation. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, using version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.