Provided by: grokevt_0.4.1-7_all bug

NAME

       GrokEVT  -  a collection of scripts built for reading windows event log
       files.

DESCRIPTION

       This document serves as an overview  to  using  the  GrokEVT  suite  of
       tools. Please see the man pages for each tool for specific command-line
       options.

USING

       Using GrokEVT on a set of windows partitions is a three stage  process.
       One must first mount the partitions and configure the system's profile.
       Next,  grokevt-builddb(1)  must  be  run  to  extract   the   necessary
       information from these partitions.  Finally, grokevt-parselog(1) may be
       run to use this information to convert the logs to something useful.

       Mounting and configuration:

       This is the most labor-intensive step of the process. There are several
       technical  reasons  why this cannot be simpler, and it is unlikely many
       will be resolved anytime soon. (Sorry, blame the  vendor  who  produced
       these logs that you wish to convert.)

       First  mount the partitions used by your windows system.  Specifically,
       mount any partition  that  has  software  installed  on  it.  (You  can
       probably  get  away  with  not  mounting  ones  with no software, or no
       software that produces events in the event log.)  This includes windows
       shares, if you have any with software installed on them.

       The  key  point  when  mounting  partitions or shares, is that you must
       mount them with case-insensitive filenames. To do this  in  Linux,  you
       should be able to use the NTFS option 'posix=0', or with type vfat this
       appears to be the default. On FreeBSD, one can use the -i  option  with
       NTFS  and  mount_ntfs,  but  this hasn't been tested. (More research is
       necessary in this area. Please let me  know  if  case-insensitivity  is
       available  on  other  *NIXes and what the options are.) All of this, of
       course, depends on your version of  mount  and  related  software.  See
       mount(8) for more information.

       Once you have all necessary filesystems mounted for your windows image,
       you need to configure GrokEVT so it knows where everything is.  If  you
       look   in   the   main   configuration   directory,   (by   default  at
       '/usr/local/etc/grokevt') you'll find a sub-directory called 'systems'.
       In  there  is  a  set  of system configuration profiles. Each directory
       under 'systems' represents the configuration for a single windows host.
       You  may  create  directories here of any name. It is suggested you use
       the host name of the system you wish to extract logs from.

       By default, there will be one system configuration there already, named
       'example'.  I  suggest  you  make a full copy of this, and edit it from
       there to create your own configuration:

              # cd /usr/local/etc/grokevt/systems
              # cp -r example mysystem

       Now that you have your own configuration, take  a  look  at  the  files
       under this directory:

              path-vars/%SystemRoot%
              system-registry
              drives/c:
              drives/d:

       Each  file represents a single configuration setting. The first line of
       every file is the setting, all others are ignored. You should start  by
       configuring  your drive letters. These drive letters need to map to the
       *NIX path of the drives. So, if you mounted  your  C:  partition  under
       '/mnt/win/c', then you should do the following:

              echo /mnt/win/c > drives/c:

       This  will  of course, overwrite that file with your actual mount point
       for the C: drive. Do this  for  all  drives  mounted  on  your  windows
       system.

       Next, you need to configure your %SystemRoot% path variable.  Since the
       registry often references files in relation to this variable,  we  need
       to  know  where it is on your system.  Typically, on W2K this should be
       'C:\WINNT'. On other windows systems it  is  often  'C:\Windows'.  This
       path  may  be referenced as a full windows path (with drive letters) or
       as a *NIX path.

       Finally, you need to set the path of the  system  registry.  This  path
       must be a *NIX path, and not a windows path. It should be located under
       your %SystemRoot%. For instance, if you mount a  W2K  machine's  C:  on
       '/mnt/win/c',       this       path       will       probably       be:
       /mnt/win/c/WINNT/system32/config/system

       This will vary from system to system, but if you  have  ever  done  any
       forensics, you should be able to find the correct path pretty quickly.

       Using grokevt-builddb(1):

       Once  you  get past the mounting and configuration step, you're in good
       shape. To extract the necessary information from the  system  you  just
       mounted,  you  just  need  to decide where you want to store the output
       database. Based on the example paths  above,  one  could  run  grokevt-
       builddb(1) like so:

              grokevt-builddb mysystem /var/db/grokevt/mysystem

       Or  something similar. This step will take some time, as a lot of files
       need to be parsed. You will likely get some warnings about missing DLLs
       and  possibly  service  removals.  This  is  normal  if software on the
       windows system failed to clean up the registry correctly  when  it  was
       un-installed.  You  might  want  to  record this information though, if
       later you find you are missing a lot of message templates in  your  log
       output.

       Now  that  you  have  finished  this step, you have fully extracted all
       information needed to interpret the event logs.

       Using grokevt-parselog(1):

       To run grokevt-parselog(1), you must  specify  the  database  directory
       that you generated with grokevt-builddb(1). Initially, you will want to
       find out what event logs were extracted by running:

              grokevt-parselog -l /var/db/grokevt/mysystem

       This will print out all available event log types, based on information
       found  previously  in  the  system's registry. Then you may view one of
       those logs simply by dropping the -l option, and adding  it's  name  as
       the second parameter. For instance, to view the 'System' log:

              grokevt-parselog /var/db/grokevt/mysystem System

       See the grokevt-parselog(1) man page for further options.

       Finding and Parsing Log Fragments:

       One  may  find it useful to parse deleted log files or fragments of log
       files found in a system's RAM dump. A  special-purpose  tool,  grokevt-
       findlogs(1)  is  included  in this distribution which makes finding log
       fragments easy. It can find even a single log record by itself  with  a
       relatively low rate of false positives.

       Suppose one has a file, dump.img, which contains an image of a system's
       RAM, or perhaps the unallocated blocks of a  filesystem  (as  might  be
       produced  by  The  SleuthKit's  dls(1)).  One could search this dump by
       running:

              grokevt-findlogs dump.img

       This will produce a listing of all hits in the file, which may  include
       header  records, cursor records, or log records, offsets and contiguity
       information to help one eliminate any false positives.

       Supposing we found a log fragment in this dump  that  we're  interested
       in,  we  could  simply  use  dd(1)  or some other tool to carve out the
       relevant data in to a file named fragment.evt. We'd then need to find a
       way  to  associate  this  log with a set of message templates.  This is
       what grokevt-addlog(1) is for. Let's take a guess that the fragment.evt
       was  originally  a  part  of  System log. We would add the log into our
       previously built message database by running:

              grokevt-addlog /var/db/grokevt/mysystem fragment.evt System-fragment System

       Finally, we can parse the log by simply specifying the  newly  imported
       name with grokevt-parselog(1):

              grokevt-parselog /var/db/grokevt/mysystem System-fragment

       If we found that most of the log entries didn't have associated message
       templates (which would result in lots of warnings to stderr), we  would
       be pretty that fragment.evt really wasn't based on a System log. Simply
       re-importing it as another log type (and a different name) would let us
       parse it again as if it were of another type.

       Please  see the grokevt-findlogs(1) and grokevt-addlog(1) man pages for
       more information.

CREDITS

       This man page written by Timothy D. Morgan

LICENSE

       Please see the file "LICENSE" included with this software distribution.

       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 version 2 for more details.

SEE ALSO

       grokevt-addlog(1)   grokevt-builddb(1)   grokevt-findlogs(1)   grokevt-
       parselog(1) grokevt-ripdll(1) reglookup(1)