DragonFly On-Line Manual Pages
LOG2TIMELINE(1) User Contributed Perl Documentation LOG2TIMELINE(1)
NAME
log2timeline - a log file parser that produces a body file used to
create timelines (for forensic investigations).
SYNOPSIS
log2timeline [OPTIONS] [-f FORMAT] [-z TIMEZONE] [-o OUTPUT MODULE] [-w
BODYFILE] LOG_FILE/LOG_DIR [--] [FORMAT FILE OPTIONS]
OPTIONS
-s|-skew TIME
Time skew of original machine. The format of the variable TIME
is: X | Xs | Xm | Xh, where X is a integer and s represents
seconds, m minutes and h hours (default behaviour is seconds)
-m TEXT Prepend the filename with the TEXT. That is TEXT is a string
that is prepended in front of the file name to provide a path.
Examples are -m C: to prepend the C:/ in front of each file
name to indicate the partition the file came from.
-f|-format FORMAT
Use the following log file format to parse the content of the
file. Use -f list to see the list of supported log files.
Omitting this options make log2timeline attempt to guess the
format.
-u|-upgrade
Check the latest available version of log2timeline and compare
it to current version (use to check if there is an available
update)
-name HOST
Define the host name that the information is extracted from.
-o|-output FORMAT
Use the following output format. By default log2timeline uses
the CSV output. To see a list of all available output formats,
use -o list
-d|-detail
Some input modules have the capability to include very detailed
amount of information (such as MFT, setupapi and prefetch).
This switch will instruct modules to include those details in
the timeline, so for instance to tell the MFT module to include
the $FN timestamps, or the prefetch one to include loaded DLLs.
-w|-write FILENAME
Specify a file to write output to (otherwise STDOUT will be
chosen).
-z|-zone TIMEZONE
This option defines the timezone that was used on the computer
that the log files belonged to. The default value for this
variable is the local timezone of the computer log2timeline is
run on. There is an option to define -z list to get a list of
all available timezones.
-Z|-Zone TIMEZONE
This option defines the timezone that is used in the output
module of the tool. The default value for this variable is the
same value that is defined in the -z option or the timezone of
the host. This option is used so that output modules can output
in a different timezone than the host is in, for instance to
output in UTC even though the timezone of the host is in
another timezone.
-t|-temp DIR
This option defines the temporary directory the tool uses. By
default the front-end does not set the temporary directory, but
allows the engine to automatically detect it. This option
therefore overwrites the default temporary directory location.
The engine checks the operating system in question, if it is
Windows, it will try to determine the temporary path based on
the Win32::API (so this might fail on 64-bit systems, perhaps
better to use this option to set it manually on those systems).
Otherwise it will use /tmp/ as the temporary directory (should
work on *NIX systems).
-log FILENAME
Specify a file to write error and information messages from the
log2timeline to a file, otherwise STDERR will be used.
-c|-calculate
If this option is used then a MD5 sum is calculated for the
file and stored in the timestamp object
-x Make log2timeline skip some more detailed tests to see if a
file truly is in the correct input module. The tool should
work faster with this option, however it might miss some files.
-e|-exclude LIST
A comma separated list of files to exclude from the scan. If a
particular file has caused the tool to crash or not work, or
you simply want to exclude some documents from the scan it is
possible to exclude some
-r|-recursive
This option makes log2timeline work in a recursive way, the
same behaviour as timescanner.
-p|-preprocess
If log2timeline is working in recursive mode (-r) it is
possible to use the -p option to run a set of pre-processors
agains the image file. Preprocessors are modules that search
through the suspect drive and extract needed information that
can be used in other modules, such as hostname, etc.
-v|-verbose
Add debugging information. Possible to use with -v -v to
increase some error messages.
-V|-Version
Display the version number
-h|-help|-?
Display this help message
Better description can be read in the man page of the program (man
log2timeline).
DESCRIPTION
log2timeline takes a log file (or a directory) and parses it to produce
a body file that can be imported into other tools for timeline
analysis. The tool has both a modular based approach to the input file
as well as the output file. The current version supports exporting the
timeline in a several different body formats. log2timeline is build as
a series of scripts, this one being the front-end, which uses other
scripts to actually parse the log files (called format files). The tool
is build to be easily extended for anyone that wants to create a new
format or an output file.
As noted above the default output mechanism is in a CSV file format,
which can be easily imported into spreadsheet applications, and parsed
by the tool l2t_process. The output format can be easily changed with
the -o parameter. The output module can be set to output in a body
format that needs to be imported into another tool for human readable
format, or it can be implemented to print the timeline directly in a
human readable format.
The tool is build using multiple so called input modules. Each of
those input modules provide a single format that can be parsed, whether
that is a log file or a directory containing some files that need to be
parsed.
The purpose of the tool is to provide a single tool to parse various
artifacts that are either produced by the suspsect operating system or
other systems that might have some logs retaining to the investigation.
OVERVIEW
Furhter description of the parameters
-s|-skew TIME
Time skew of original machine. It is added (or subtracted) from
each time (ctime,atime,mtime,crtime) in the bodyfile to
compensate for different time in some log files from the
"correct" time. The format of the variable TIME is:
X | Xs | Xm | Xh
Where X is a integer and s represents seconds, m minutes
and h hours (default behaviour is seconds) It is possible
to prepend TIME with a minus sign (-) to indicate that the
time skew is a negative number.
Example of this usage is: log2timeline -t 1243 (a time skew
of +1243 seconds is added to each time)
-m TEXT Prepend the filename with the TEXT. That is TEXT is a string
that is prepended in front of the file name to provide a path.
Examples are -m C: to prepend the C:/ in front of each file
name to indicate the partition the file came from.
-d|-detail
Some input modules have the capability to include very detailed
amount of information (such as MFT and prefetch). This switch
will instruct modules to include those details in the timeline,
so for instance to tell the MFT module to include the $FN
timestamps, or the prefetch one to include loaded DLLs.
By default the MFT input module will only include the
$STANDARD_INFORMATION timestamps, not the $FILE_NAME. This is
due to the fact that in most cases these timestamps may not
matter as much. However, especially in intrusion cases, these
timestamps play a valiable role. Therefore this option exists
to indicate to the tool that it should include the $FN
timestamps in addition to the $SN ones.
The same goes with the prefetch module. It can potentially
include information about all DLLs each prefetch loads up. This
might be a very useful information to have when dealing with
malware cases, but it might be too much details in most cases.
Hence this is omitted now by default, unless the -d parameter
is set.
The setupapi input module also includes lot of verbose text
that can be reduced to make the timeline more concise. This
information is now by default omitted in the timeline unless
this parameter is turned on.
So this parameter tells input modules to include more detailed
information about the events. Not all input modules will honor
this option, however more might come, and by default this
option is not set.
-u|-upgrade
Check the latest available version of log2timeline and compare
it to current version (use to check if there is an available
update). What this option does is to fetch a file
http://log2timeline.net/VERSION, which contains a single
number, which reflects the latest released version of the tool.
This version number is then compared to the tools version
number to find out if there is a new version available on the
official site.
-f|-format FORMAT
log2timeline has the capability to automatically detect the
format of the log file. If this option is omitted log2timeline
will attempt to guess the source file format. However the
behaviour can be overwritten with this option. So if the -f
parameter is set the tool will only use that input module to
test against the log file.
It is possible to either define a single input module, list of
them or a name of a list file that contains a list of input
modules to use.
To get a list of all available input modules use the option of
-f list.
-name HOST
Define the host name that the information is extracted from.
-o|-output FORMAT
Use the following output format. By default log2timeline uses
the CSV output. To see a list of all available output formats,
use -o list
This option works the same way as the format file option does
(-f) in the way that it searches the output folder for a file
called FORMAT.pl and uses that to print the output that has
been generated previously by the format file. The tool dies if
the script FORMAT.pl does not exist or is of the wrong format
(with an exit code of 13).
-w|-write FILENAME
The standard way to output the bodyfile or timeline is by using
standard output (STDOUT). That can be overwritten using this
option to redirect the output to a file.
-v|-verbose
Add debugging information
-z|-zone TIMEZONE
This option defines the timezone that was used on the computer
that the log files belonged to. The default value for this
variable is the local timezone of the computer log2timeline is
run on. Depending on the supplied artifact it may be written
using the timestamps from the original computer's timezone or
it may be written in predefined timezone, such as UTC.
If the "-z local" timezone is chosen the tool will print the
found local timezone.
The option -z list prints out a list of all available timezones
that can be chosen.
-Z|-Zone TIMEZONE
This option defines the timezone that is used in the output
module of the tool. The default value for this variable is the
same value that is defined in the -z option or the timezone of
the host. This option is used so that output modules can output
in a different timezone than the host is in, for instance to
output in UTC even though the timezone of the host is in
another timezone.
-t|-temp DIR
This option defines the temporary directory the tool uses. By
default the front-end does not set the temporary directory, but
allows the engine to automatically detect it. This option
therefore overwrites the default temporary directory location.
The engine checks the operating system in question, if it is
Windows, it will try to determine the temporary path based on
the Win32::API (so this might fail on 64-bit systems, perhaps
better to use this option to set it manually on those systems).
Otherwise it will use /tmp/ as the temporary directory (should
work on *NIX systems).
-log FILENAME
Specify a file to write error and information messages from the
log2timeline to a file, otherwise STDERR will be used.
-c|-calculate
If this option is used then a MD5 sum is calculated for the
file and stored in the timestamp object
-x log2timeline will by default try to run a minimized test on the
input file to determine if it is of the correct structure. For
instance only to test the first byte to see if it matches.
This could lead to some files not being detected by
log2timeline. Therefore the -x option is provided to skip this
pre-test and move directly to a more comprehensive test that is
otherwise done after the pre-test is successful. This might
lead to fewer false positives, but in turn makes the tool a bit
slower.
-V|-Version
Display the version number of the tool log2timeline and exit
with the exit code 0.
-h|-help|-?
Display a help message explaining the available options to the
tool (a simple version of this man page).
-e|-exclude LIST
A comma separated list of files to exclude from the scan. If a
particular file has caused the tool to crash or not work, or
you simply want to exclude some documents from the scan it is
possible to exclude some
Example:
log2timeline -f winvista -r -z local -e
'Windows-Diagnosis,secret[0-3]' /mnt/windows
This would scan all the directory /mnt/windows
recursively, using only modules associated to a Windows
Vista or later operating system, and excluding all
filenames that have "Windows-Diagnosis" in them or
contain the word secret0/secret1/secret2 or secret3 in
it.
-r|-recursive
This option makes log2timeline work in a recursive way, the
same behaviour as timescanner.
-p|-preprocess
If log2timeline is working in recursive mode (-r) it is
possible to use the -p option to run a set of pre-processors
agains the image file. Preprocessors are modules that search
through the suspect drive and extract needed information that
can be used in other modules, such as hostname, etc.
EXAMPLES
log2timeline -f list
Print a list of all available format files.
log2timeline -f firefox3 -z EST5EDT -w /tmp/bodyfile places.sqlite --
-u JOE 2> /tmp/body.log
Use the Firefox 3 history parser to parse a places.sqlite file
that contains history information. Prepened the output with
information about the user that owned the file, in this case
the user JOE owned this history file. The output, which is in
the TLN format will be written to the file body, while all log
messages are written to the file body.log (STDERR is redirected
to a file)
log2timeline -z local -f squid -s 2h access.log > squid.body
Parses an access log file from Squid to produce a body file
that is output into the file squid.body. Two hours are added
to each time in the timeline to correct the time settings of
the log file that is parsed.
log2timeline -z GMT -f prefetch WINDOWS/Prefetch >> case.body
Parses the content of the Windows Prefetch directory and adds
the timeline to the already available case.body timeline.
log2timeline -f recycler -z local -o sqlite -w /tmp/rec.sql
RECYCLER/S-1-5-21-..../
Parses the content of the INFO2 file, found inside each recycle
bin and prints out information into a SQLite database
(/tmp/rec.sql).
log2timeline -z local -f winxp -r -p /mnt/analyze
Make log2timeline recursively go through the mount point
/mnt/analyze using the available input modules that are stored
inside the winxp list file (those that are relevant to a
Windows XP machine). Before running the recursive scan the
pre-processing modules are ran against the image to gather
information from it.
RETURN VALUE
0 Successful program execution
1 Wrong usage of the log2timeline program. Possibly omitting the
-f parameter or a file name to parse.
12 Problem loading the format file. Format file not found, not
correctly formed or otherwise unable to parse the format file.
13 Problem loading the output file. Output file not found, not
correctly formed or otherwise unable to parse the content of
the output file.
14 Unable to verify the log file. That is the format file is
unable to verify that the log file is of the correct format.
15 Unable to open the log file. Perhaps because you don't have
permission to read the content of the log file.
20 Problem writing to output file.
45 The supplied timezone does not exist.
BUGS
As of now there are no known bugs, and when bugs are either discovered
or reported they are fixed as soon as possible and made available in
the nightly builds.
If you find a bug in the tool, please start by downloading the latest
build (nightly builds) available at
http://log2timeline.net/files/log2timeline_nightly.tgz to verify that
the bug hasn't already been fixed and if it hasn't please report the
problem to Kristinn Gudjonsson (bugs ( a t ) log2timeline ( d o t )
net.
There are few known limitations though:
+ The LSO (.sol) input module isn't able to properly parse every .sol
file it finds. The payload of a .sol file is encoded using Action
Message Format from Adobe. There are two versions of AMF, AMF0 and
AMF3. The vast majority of .sol files is encoded using the AMF0,
however there are some that use AMF3. The current version of the sol
parser only works against AMF0, however a version that supports AMF3
should be released in not so distant future.
+ There have also been reports about log2timeline not properly clean
temporary files after completing it's run. This behaviour involves the
input modules for Chrome and Firefox history. If the input module
detects a database that is being locked, it copies the database to a
temporary location to be able to connect and properly parse the file.
After it has completed the parsing it will try to delete the temporary
file using the Perl function unlink. If you do have this problem
please notify the author to see if we can figure this out together and
fix the problem.
HISTORY
For a full history of releases please refer to the changelog. This list
only provides a brief high level overview of the first few releases, it
is no longer maintained. Full changelog can be found on the tool's code
site (https://code.google.com/p/log2timeline) and in the CHANGELOG that
comes with the source.
v0.1b Initial release.
v0.11b (20/07/2009) Mostly few bug fixes.
v0.12b (31.07.2009) New features implemented, refining of code.
v0.20b (04.08.2009) Bug fixes, changes in the structure and new input
modules introduced.
v0.21b (07.08.2009) Bug fixes, changes in the structure and new input
modules introduced.
v0.22b (10.08.2009) New input modules.
v0.30b (02/09/09) Changes to the structure, first release of a GUI, bug
fixes and common libraries used.
v0.31b (07/09/09) New modules, new front-end timescanner introduced.
Small bug fixes.
v0.32b (10/09/09) Bug fixes, new input modules as well as libraries.
Version checking implemented.
v0.33b (15/09/09) Bug fixes.
v0.40 (25/11/09) Changes in the structure, timestamps normalized to
UTC. Bug fixes, improvements in modules, new input modules.
v0.41 (15/01/10) New input modules, bug fixes, improvements of older
modules, new update mechansim introduced.
0.42 (05/03/10) New input modules (pdf,mcafee), bug fixes, improvements
of older modules and the main tool
0.50 (30/06/10) New timestamp object introduced, every module updated
along with front-ends, bug fixes and improvements
0.51 (14/12/2010) New input modules alongside several bug fixes.
0.52 (05/04/2011) New input modules alongside several bug fixes.
0.60 (05/06/2011) Core redesign of the tool, moving the engine to a
separate library and several other changes.
0.60+ not described here any more... list kept for legacy reasons.
AUTHOR
Kristinn Gudjonsson <kristinn (a t) log2timeline ( d o t ) net> is the
original author of the program.
The tool is released under GPL so anyone can contribute to the tool.
Some parts of the code have been copied from other GPL'ed programs,
such as the Parse::Evtx library by Andreas Schuster, and parts of
RegRipper written by H. Carvey.
COPYRIGHT AND LICENSE
Copyright 2009-2012 by Kristinn Gudjonsson (kristinn ( a t )
log2timeline ( d o t ) net )
log2timeline 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, either version 3 of the License, or (at your
option) any later version.
log2timeline 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 log2timeline. If not, see <http://www.gnu.org/licenses/>.
SEE ALSO
Log2Timeline
perl v5.20.2 2012-05-22 LOG2TIMELINE(1)