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