NAME

log2timeline - a log file parser that produces a body file used to create timelines (for forensic investigations).


SYNOPSIS

log2timeline [OPTIONS] -f FORMAT 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 output line with TEXT, for instance by using -m HOSTNAME to include a hostname in the output

-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

-c|-check

Check the latest available version of log2timeline and compare it to current version (use to check if there is an available update)

-o|-output FORMAT

Use the following output format. By default log2timeline uses the mactime output. To see a list of all available output formats, use -o list

-l|-legacy

Legacy format for TSK version 1.x and 2.x, otherwise version 3.+ assumed. This option implies "-o mactime_l"

-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.

-log FILENAME

Specify a file to write error and information messages from the log2timeline to a file, otherwise STDERR will be used.

-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

-- [FORMAT FILE OPTIONS]

Some format files accept options being sent to it. Please see log2timeline -f FORMAT -h to see which options are supported. The option -- must prepend any options send to a format file (example -- -u USER to send the -u USER option to a format file)

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 body format readable by TSK's (The SleuthKit) mactime. 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 current supported output is the body format used by mactime. For further information about the ouptput format, please read http://wiki.sleuthkit.org/index.php?title=Body_file. Other output formats can be easily created by the use of an output file. The output file 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 format files, which are stored in the format folder. Each of those format files 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 output line with TEXT. That is TEXT is a string that is included in each line of the output in the name part of the timeline. The string is wrapped with the signs '<' and '>' and prepended before other text in the name field.

This field is often used to represent the name of the host that particular log file was found on.

This field is used as a host name field for some output plugins that require a host name in it's output.

-c|-check

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 does not automatically detect the format of the log file (yet) so it is necessary to include this parameter to tell the script which format the log file is of.

The way this parameter works is that it takes the FORMAT and parses the file FORMAT.pl found inside the format folder (default /usr/local/share/log2timeline/format). It uses that Perl script to parse the content of the log file that is provided as the last parameter. The tool dies if the script FORMAT.pl does not exist or is of the wrong format (with an exit code of 12).

To get a list of all available format files, it is possible to use list as the value of the option -f, that is to use log2timeline -f list

-o|-output FORMAT

Use the following output format. By default log2timeline uses the mactime 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).

-l|-legacy

Legacy format for TSK version 1.x and 2.x, otherwise version 3.+ assumed. To see the difference between the two formats, please refer to http://wiki.sleuthkit.org/index.php?title=Body_file which explains the format of the two in greater detail.

BThis option is in fact a shorter version of the option "-o mactime_l" (provides the same functionality) and is being kept for compatability reasons (for older version of log2timeline).

-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.

-log FILENAME

Specify a file to write error and information messages from the log2timeline to a file, otherwise STDERR will be used.

-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).

-- [FORMAT FILE OPTIONS]

Some format files accept options being sent to it. Please see log2timeline -f FORMAT -h to see which options are supported. The option -- must prepend any options send to a format file (example -- -u USER to send the -u USER option to a format file)


EXAMPLES

log2timeline -f list

Print a list of all available format files.

log2timeline -f firefox3 -w body places.sqlite -- -u JOE 2> 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 mactime 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 -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 -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 -o sqlite -w /tmp/rec.sql INFO2

Parses the content of the INFO2 file, found inside each recycle bin and prints out information into a SQLite database (/tmp/rec.sql).


RETURN VALUE

  1. Successful program execution

  2. Wrong usage of the log2timeline program. Possibly omitting the -f parameter or a file name to parse.

  3. Problem loading the format file. Format file not found, not correctly formed or otherwise unable to parse the format file.

  4. Problem loading the output file. Output file not found, not correctly formed or otherwise unable to parse the content of the output file.

  5. Unable to verify the log file. That is the format file is unable to verify that the log file is of the correct format.

    
    =item B<15>

    Unable to open the log file. Perhaps because you don't have permission to read the content of the log file.

  6. Problem writing to output file.

  7. 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. Some of the .sol files seem to have different binary structure (partially) than the input module is designed for. For those files that contain this different structure, the author has not seen any other parsers being able to properly display that data any way. Perhaps in future versions the author will reverse engineer that binary structure as well and update the SOL input module, but until that day comes, bear this limitation in mind.

+ 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. There have been reports


HISTORY

For a full history of releases please refer to the changelog.

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 () New input modules, bug fixes, improvements of older modules, new update mechansim introduced.


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-2010 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/>.