NAME
HoneyClient::Agent::Integrity::Registry - Perl extension to perform static checks of the Windows OS registry.
VERSION
This documentation refers to HoneyClient::Agent::Integrity::Registry version 0.98.
SYNOPSIS
use HoneyClient::Agent::Integrity::Registry;
use Data::Dumper;
# Create the registry object. Upon creation, the object
# will be initialized, by collecting a baseline of the registry.
my $registry = HoneyClient::Agent::Integrity::Registry->new();
# ... Some time elapses ...
# Check the registry, for any changes.
my $changes = $registry->check();
if (!defined($changes)) {
print "No registry changes have occurred.\n";
} else {
print "Registry has changed:\n";
print Dumper($changes);
}
# $changes refers to an array of hashtable references, where
# each hashtable has the following format:
#
# $changes = [ {
# # The registry directory name.
# 'key_name' => 'HKEY_LOCAL_MACHINE\Software...',
#
# # Indicates if the registry directory was deleted (0),
# # added (1), or changed (2).
# 'status' => 0 | 1 | 2,
#
# # An array containing the list of entries within the
# # registry directory that have been deleted, added, or
# # changed. If this array is empty, then the corresponding
# # registry directory in the original and new hives contained
# # no entries.
# 'entries' => [ {
# 'name' => "\"string\"", # A (potentially) quoted string;
# # "@" for default
# 'new_value' => "string", # New string; maybe undef, if deleted
# 'old_value' => "string", # Old string; maybe undef, if added
# }, ],
# }, ]DESCRIPTION
This library allows the Integrity module to easily baseline and check the Windows OS registry hives for any changes that may occur, while instrumenting a target application.
This library uses modified code from the 'regutils' library by John Rochester and Michael Rendell. See http://www.cs.mun.ca/~michael/regutils/ for more information.
DEFAULT PARAMETER LIST
When a Registry $object is instantiated using the new() function, the following parameters are supplied default values. Each value can be overridden by specifying the new (key => value) pair into the new() function, as arguments.
hives_to_check
This parameter indicates the default array of registry hive names to monitor for changes.
key_dirnames_to_ignore
This parameter indicates the default array of regular expressions that each registry directory will be checked against. Any matching key directory names will be ignored and any subsequent additions, deletions, or changes to all content in these matches will also be ignored.
Each $entry will be used via the syntax /$entry/. Thus, it is recommended to specify the ^ prefix and $ suffix, when possible.
A single backslash (\) must be represented using triple backslashes (\\\) and each $entry must not end with any backslash character.
bypass_baseline
When set to 1, the object will forgo any type of initial baselining process, upon initialization. Otherwise, baselining will occur as normal, upon initialization.
METHODS IMPLEMENTED
The following functions have been implemented by any Registry object.
HoneyClient::Agent::Integrity::Registry->new($param => $value, ...)
Creates a new Registry object, which contains a hashtable containing any of the supplied "param => value" arguments. Upon creation, the Registry object performs a baseline of the Windows registry.
Inputs: $param is an optional parameter variable. $value is $param's corresponding value.
Note: If any $param(s) are supplied, then an equal number of corresponding $value(s) must also be specified.
Output: The instantiated Registry $object, fully initialized.
$object->check(before_file => $before_filename, after_file => $after_filename)
Checks the registry for any changes, based upon the baseline snapshot of the registry, when the new() method was invoked.
Inputs: $before_filename is an optional parameter, specifying the registry dump to use as the baseline, rather than using any baseline that was performed during the $object->new() operation. $after_filename is an optional parameter, specifying the registry dump to use as the checkpoint, rather than creating new a registry checkpoint to compare against.
Output: $changes, which is an array of hashtable references, where each hashtable has the following format:
$changes = [ {
# The registry directory name.
'key_name' => 'HKEY_LOCAL_MACHINE\Software...',
# Indicates if the registry directory was deleted (0),
# added (1), or changed (2).
'status' => 0 | 1 | 2,
# An array containing the list of entries within the
# registry directory that have been deleted, added, or
# changed. If this array is empty, then the corresponding
# registry directory in the original and new hives contained
# no entries.
'entries' => [ {
'name' => "\"string\"", # A (potentially) quoted string;
# "@" for default
'new_value' => "string", # New string; maybe undef, if deleted
'old_value' => "string", # Old string; maybe undef, if added
}, ],
}, ]Notes: If $before_filename is specified, then $after_filename must be specified as well.
$object->getFilesCreated()
Returns a list of temporary filenames that have been created by the Registry $object.
Output: Returns a list of filenames.
$object->closeFiles()
Closes any temporary files that have been created by the Registry $object. By performing this operation, the Registry $object can become serializable.
BUGS & ASSUMPTIONS
By default, this module performs a baseline integrity check on the Windows OS registry during the $object->new() call. The $object->check() call will return any visible changes found in the registry, between these two calls.
Any changes that occur to the Windows registry that are performed and then undone between these integrity checks WILL NOT BE DISCOVERED by the $object->check() operation.
This module relies on the REGEDIT.EXE utility program that is standard on all Windows OS installations. Because REGEDIT.EXE does not expose null-encoded registry directory keys, this module will NOT be able to identify any adds, deletions, and/or changes to these types of directory keys.
The $object->new() and $object->check() calls may generate a large number of temporary files on disk. If any of this code fails prematurely, then it's likely these temporary files will still exist upon abnormal termination. As such, manual cleanup of these files in /tmp may be required.
For more information about the limitations of this module, please see:
http://www.honeyclient.org/trac/wiki/ParsingRegistry
SEE ALSO
http://www.cs.mun.ca/~michael/regutils/
http://www.honeyclient.org/trac
REPORTING BUGS
http://www.honeyclient.org/trac/newticket
ACKNOWLEDGEMENTS
John Rochester <jr@cs.mun.ca> and Michael Rendell <michael@cs.mun.ca> from the Memorial University of Newfoundland, for using core code from their regutils package, in order to perform diff operations on registry hives.
AUTHORS
Darien Kindlund, <kindlund@mitre.org>
Xeno Kovah, <xkovah@mitre.org>
COPYRIGHT & LICENSE
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.