/ 
HoneyClient-Agent-0.98-stable
River stage zero No dependents
/ HoneyClient::Agent::Integrity::Filesystem

NAME

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

VERSION

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

SYNOPSIS

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

DESCRIPTION

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.

DEFAULT PARAMETER LIST

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.

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.

baseline_analysis

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

monitored_directories

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

ignored_entries

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

METHODS IMPLEMENTED

The following functions have been implemented by any Filesystem object.

HoneyClient::Agent::Integrity::Filesystem->new($param => $value, ...)

    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.

$object->check(no_prepare => $no_prepare)

    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.

BUGS & ASSUMPTIONS

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.

SEE ALSO

http://www.honeyclient.org/trac

REPORTING BUGS

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

ACKNOWLEDGEMENTS

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

AUTHORS

Xeno Kovah, <xkovah@mitre.org>

Darien Kindlund, <kindlund@mitre.org>

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