HoneyClient::Agent::Integrity::Filesystem - Perl extension to perform static checks of the Windows OS filesystem.

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

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

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

  # ... Some time elapses ...

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

  if (!defined($changes)) {
      print "No filesystem changes have occurred.\n";
  } else {
      print "Filesystem has changed:\n";
      print Dumper($changes);
  }

  # $changes refers to an array of hashtable references, where
  # each hashtable has the following format:
  #
  # $changes = [ {
  #     # Indicates if the filesystem entry was deleted,
  #     # added, or changed.
  #     'status' => $STATUS_DELETED | $STATUS_ADDED | $STATUS_MODIFIED,
  #     'name'  => 'C:\WINDOWS\SYSTEM32...',
  #     'mtime' => 'YYYY-MM-DD HH:MM:SS', # new mtime for added/modified files;
  #                                       # old mtime for deleted files
  #
  #     # content will only exist for added/modified files
  #     'content' => {
  #         'size' => 1263,                                       # size of new content 
  #         'type' => 'application/octect-stream',                # type of new content
  #         'md5'  => 'b1946ac92492d2347c6235b4d2611184',         # md5  of new content
  #         'sha1' => 'f572d396fae9206628714fb2ce00f72e94f2258f', # sha1 of new content
  #     },
  # }, ]

This library allows the Integrity module to easily baseline and check the Windows OS filesystem for any changes that may occur, while instrumenting a target application.

When a Filesystem $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.

An array of hashtables used to hold the file analysis information, for the baseline filesystem operation.

The base list of drives, directories, and/or files to monitor.

The list of regular expressions that match drives, directories, and/or files to exclude from analysis.

The following functions have been implemented by any Filesystem object.

Creates a new Filesystem object, which contains a hashtable containing any of the supplied "param => value" arguments. Upon creation, the Filesystem object performs a baseline of the Windows filesystem.

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

Checks the filesystem for various changes, based upon the filesystem baseline, when the new() method was invoked.

Inputs:$no_prepare is an optional parameter, specifying the output format of the changes found.

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

  If $no_prepare == 1, then the format will be:

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

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

  Otherwise, the format will be:

  $changes = [ {
      # Indicates if the filesystem entry was deleted,
      # added, or changed.
      'status' => $STATUS_DELETED | $STATUS_ADDED | $STATUS_MODIFIED,
      'name'  => 'C:\WINDOWS\SYSTEM32...',
      'mtime' => 'YYYY-MM-DD HH:MM:SS', # new mtime for added/modified files;
                                        # old mtime for deleted files

      # content will only exist for added/modified files
      'content' => {
          'size' => 1263,                                       # size of new content 
          'type' => 'application/octet-stream',                 # type of new content
          'md5'  => 'b1946ac92492d2347c6235b4d2611184',         # md5  of new content
          'sha1' => 'f572d396fae9206628714fb2ce00f72e94f2258f', # sha1 of new content
      },
  }, ]

Notes: If $no_prepare != 1 or $no_prepare == undef, then the outputted changes will NEVER refer to any directories. All the changes will correspond to individual files.

This library performs STATIC checks of the Windows filesystem. If malware modifies the filesystem between the time the $object->new() and $object->check() methods are called, then this library may FAIL to detect those changes if:

• Malware writes itself to one of the regions of the filesystem that is excluded. See the <HoneyClient/><Agent/><Integrity/><exclude_list/> element, in the etc/honeyclient.xml file.
• Malware writes itself to a monitored region of the filesystem but reverses all its activity (including self-deletion).

This library also only monitors FILE changes. Thus, if malware manipulates EMPTY DIRECTORIES or SYMLINKS on the system, then this library will NOT report those changes.

http://www.honeyclient.org/trac

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

Mark-Jason Dominus <mjd-perl-diff@plover.com>, Ned Konz <perl@bike-nomad.com>, and Tye McQueen, for using their Algorithm::Diff code.

Xeno Kovah, <xkovah@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.