HoneyClient::Agent::Integrity - Perl extension to perform configurable integrity checks of the Agent VM OS.

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

  use HoneyClient::Agent::Integrity;
  use Data::Dumper;

  # Create the Integrity object.  Upon creation, the object will
  # be initialized, by performing a baseline of the Agent VM OS.
  my $integrity = HoneyClient::Agent::Integrity->new();

  # ... Some time elapses ...

  # Check the Agent VM, for any violations.
  my $changes = $integrity->check();

  if (!defined($changes)) {
      print "No integrity violations have occurred.\n";
  } else {
      print "System integrity has been compromised:\n";
      print Dumper($changes);
  }

  # $changes refers to an array of hashtable references, where
  # each hashtable has the following format:
  #
  # $changes = {
  #     registry => [ {
  #         # The registry directory name.
  #         'key' => 'HKEY_LOCAL_MACHINE\Software...',
  #
  #         # Indicates if the registry directory was deleted,
  #         # added, or changed.
  #         'status' => 'deleted' | 'added' | 'changed',
  # 
  #         # 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
  #         }, ],
  #    }, ],
  #
  #    filesystem => [ {
  #         # Indicates if the filesystem entry was deleted,
  #         # added, or changed.
  #         'status' => 'deleted' | 'added' | 'changed',
  #
  #         # If the entry has been added/changed, then this 
  #         # hashtable contains the file/directory's new information.
  #         'new' => {
  #             'name'  => 'C:\WINDOWS\SYSTEM32...',
  #             'size'  => 1263, # in bytes
  #             'mtime' => 1178135092, # modification time, seconds since epoch
  #         },
  #
  #         # If the entry has been deleted/changed, then this
  #         # hashtable contains the file/directory's old information.
  #         'old' => {
  #             'name'  => 'C:\WINDOWS\SYSTEM32...',
  #             'size'  => 802, # in bytes
  #             'mtime' => 1178135028, # modification time, seconds since epoch
  #         },
  #   }, ],
  # }

# TODO: This text needs to change.

# TODO: This text needs to change.

In order to properly check the system, a snapshot must be taken of a known-good state.

For the filesystem this means a listing is created which contains cryptographic hashes of files in their start state. The only files what are checked are those which are explicitly specified in the checklist file (or are found in a specified directory) and are not in the exclusion list will be checked. Initialization of the filesystem is done with the initFileSystem() function, described later.

For the registry a similar logic applies in that the only the specified keys are checked and only if they are not in the exclusion list. The desired registry keys are exported to a text file via the command line functionality of regedit. This is done via initRegistry().

# TODO: This text needs to change.

Checking the filesystem entails running mostly the same code as the initialization piece in order to obtain a snapshot of the current state of the filesystem. At that point additional checks are performed to look for additions, deletions, and modifications to the filesystem. These checks are done with checkFileSystem().

A speed-optimized check of the registry is performed by first dumping the current state, again with the command line version of regedit. Then the unix "diff" utility is used to compare the clean registry dump to the current one. The output from a diff is in a format which shows the minimum possible changes which can be done to the first file in order to yield the same content as the second file. Therefore this format must be parsed in order to determine what specific additions, deletions, and modifications were made to the clean registry. Further, because the output of diff need not exactly reflect changes (for instance when the same content would be the first line of the previous value and the last line of the new value) this requires some cases to re-consult the original and current state in order to disambiguate the changes which were made. These tests are done in checkRegistry().

NOTE: Because these are simple, static, user-space checks, they can fail in the presense of even user-space rootkits. Therefore these checks should not be taken as definitive proof of the absense of malicious software until they are integrated more tightly with the system.

When an Integrity $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.

When set to 1, the object will forgo any type of initial baselining process, upon initialization. Otherwise, baselining will occur as normal, upon initialization.

The following functions have been implemented by any Integrity object.

Creates a new Integrity object, which contains a hashtable containing any of the supplied "param => value" arguments. Upon creation, the Integrity object initializes all of its sub-modules, by creating a baseline of the operating system.

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 Integrity $object, fully initialized.

Checks the operating system for various changes, based upon the baseline snapshot of the system, when the new() method was invoked.

Output:$changes, which is an array of hashtable references, where each hashtable has the following format:

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

          # Indicates if the registry directory was deleted,
          # added, or changed.
          'status' => 'deleted' | 'added' | 'changed',

          # 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
          }, ],
      }, ],

      filesystem => [ {
          # Indicates if the filesystem entry was deleted,
          # added, or changed.
          'status' => 'deleted' | 'added' | 'changed',

          # If the entry has been added/changed, then this 
          # hashtable contains the file/directory's new information.
          'new' => {
              'name'  => 'C:\WINDOWS\SYSTEM32...',
              'size'  => 1263, # in bytes
              'mtime' => 1178135092, # modification time, seconds since epoch
          },

          # If the entry has been deleted/changed, then this
          # hashtable contains the file/directory's old information.
          'old' => {
              'name'  => 'C:\WINDOWS\SYSTEM32...',
              'size'  => 802, # in bytes
              'mtime' => 1178135028, # modification time, seconds since epoch
          },
      }, ],
  }

Notes:

#=begin testing # # TODO: # #=end testing

# XXX: Fill this in.

Need to add sub-modules that support the following capabilities:

• Static or real-time rogue process detection.
• Static or real-time memory alteration detection.

http://www.honeyclient.org/trac

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

XXX: Fill this in.

Kathy Wang, <knwang@mitre.org>

Xeno Kovah, <xkovah@mitre.org>

Thanh Truong, <ttruong@mitre.org>

Darien Kindlund, <kindlund@mitre.org>

Brad Stephenson, <stephenson@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.