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.