Read Me

Zeitline: a forensic timeline editor
Version: 0.2 (beta)
June 6th, 2006

This is the release for Zeitline version 0.2. See CHANGELOG for details.
Zeitline is a tool that lets a user import events from various sources and
manage those events in one or more timelines. You can import events, display
information about events, group events together into super events (using menu
actions, drag and drop, or cut and paste), create new timelines (empty or from a
selection of events), perform a basic filtering of and searches for the events
that are displayed by keyword and/or time, save and load a project, and create
your own import filters. We believe the program is fairly stable at this point,
but there are likely to be many errors left. Also, performance can probably be
improved quite a bit as well. Please report any bugs that are not in the
KNOWN_BUGS file, including a description and how to reproduce it to:

zeitline@cerias.purdue.edu.

Please note the LICENSE and ICONLICENSE files for copyright and license
information.

Zeitline was written using the Java 1.4.2 runtime environment. It was
developed mostly on Linux and MacOS X and also tested on Windows XP.
This is the last release that was developed for Java 1.4.2. Future
versions will at least require Java 1.5 to compile and run.

Compiling and running Zeitline:

Make sure your JAVA_HOME environment variable is set properly. To
compile the Java classes, type 'make' from the command line, which
compiles the source files and places the class files into the 'class'
directory.

If you cannot (or don't want to) run make (most Windows platforms),
you can change to the 'src' directory and type:

javac -d ../class *.java

You can run the program directly from the 'class' directory by typing:

java Zeitline

if the missing toolbar icons are bothering you, create a symbolic link
to the 'icons' directory from the class directory:

ln -s ../icons

To generate a JAR-file, type 'make jar' and run Zeitline as follows:

java -jar Zeitline.jar


Using Zeitline:

Data is added to the project by the import functionality.  Currently
Zeitline supports output files generated by the FLS and ILS tools in
machine readable format, as well as a Linux syslog filter.  FLS was
written by Brian Carrier and is included as part of the Sleuthkit
forensics package (www.sleuthkit.org).  ILS was written by Wietse
Venema and is part of The Coroner's Toolkit
(www.porcupine.org/forensics/tct.html) as well as the Sleuthkit.  See
fls(1) and ils(1) for more details. In general, be sure to invoke
FLS/ILS with the '-m' flag.

Examples written by Brian on how to generate FLS output as part of a
forensic investigation can be found at:

http://www.honeynet.org/scans/scan15/proj/bc/
http://www.honeynet.org/scans/scan29/sol/carrier/index.html

The disk image for Scan 15 can be found at:

http://www.honeynet.org/scans/scan15/honeynet.tar.gz

and an FLS file can be generated with

fls -r -m / honeypot.hda8.dd > scan15.fls

This will generate about 15,000 events and it takes about
15 seconds for Zeitline to import them. We have included this
file in the 'examples' directory.

For Zeitline FLS files should end in the '.fls' extension for the sake
of the import dialog's file filter.  Running the FLS import filter may
cause some error messages to be displayed, complaining about improper
line format. This is due to the fact that FLS and ILS display the file
names as found. For re-allocated files that means that the newline
character may be part of the file name. This is fixed in version 2.0
of FLS.  The error messages will not impact the functionality of
Zeitline, but one should be aware that those events are not imported.

Syslog filter files need not have a specific suffix. We do not
provide any example files, but syslog files normally are present in
the /var/log/messages files under Linux. The filter will query the
user for the start year of the logs, but will correctly "count forward"
the year when entries switch to an earlier month (assuming that there is
no gap in the logs that is greater than a whole year).

Additional import types will be added as Zeitline matures.

The save and load functionality refer to the saving and loading of
Zeitline-formatted project files. Loading a project will cause any
unsaved changes to be lost and currently we do not do any error
checking on the file we attempt to load. Saved Zeitline projects are
not compatible between different versions of the tool yet.

We would like to thank Brian Carrier and Sundar Jeyaraman for valuable
suggestions and helpful discussions as well as the countless authors
who have posted helpful Java GUI programming hints and examples in
various discussion forums.