Log2timeline timeline generation: Using log2timeline

# Using log2timeline.py

**log2timeline** is a command line tool to extract [events](Scribbles-about-events.md#what-is-an-event)
from individual files, recursing a directory, for example a mount point, or
storage media image or device. log2timeline creates a Plaso storage file which
can be analyzed with the pinfo and psort tools.

The Plaso storage file contains the extracted events and various metadata about
the collection process alongside information collected from the source data. It
may also contain information about tags applied to events and reports from
analysis plugins.

To get a complete list of all switches and parameters of log2timeline.py, use
``-h`` or ``--help``.

This guide will cover the most basic options and then discuss some of the
perhaps less used ones.

## Basic usage

The simplest way, and perhaps the most common way to run log2timeline.py without
any additional parameters, only defining the output and input. The output is
the path and filename of the storage file while the input is the location of
the source, whether that is a single file, a storage media image or a directory
such as a mount point. log2timeline.py will go through the entire data set and
produce a timeline with a predefined set of parsers, containing information
extracted from all discovered file entries and supported file formats.

```bash
$ log2timeline.py --storage-file OUTPUT INPUT
```

For example:

```bash
$ log2timeline.py --storage-file timeline.plaso /PATH/image.E01
2021-05-09 10:15:19,162 [INFO] (MainProcess) PID:3143504 <artifact_definitions> Determined artifact definitions path: /usr/share/artifacts/
Checking availability and versions of dependencies.
[OK]


Source path     : /PATH/image.E01
Source type     : storage media image
Processing time : 00:00:00

Processing started.
```

```bash
plaso - log2timeline version 20210412

Source path     : /PATH/image.E01
Source type     : storage media image
Processing time : 00:04:57

Tasks:          Queued  Processing      Merging         Abandoned       Total
                0       0               0               0               18675

Identifier      PID     Status          Memory          Sources         Events          File
Main            3143050 completed       1.3 GiB         18675 (0)       499347 (0)
Worker_00       3143054 idle            1.2 GiB         3275 (0)        101555 (0)      NTFS:\WINDOWS\$NtServicePackUninstall$
Worker_01       3143056 idle            1.2 GiB         4246 (0)        42476 (0)       NTFS:\WINDOWS\ie7
Worker_02       3143058 idle            1.2 GiB         675 (0)         63234 (0)       NTFS:\WINDOWS\inf
Worker_03       3143060 idle            1.2 GiB         350 (0)         57190 (0)       NTFS:\pagefile.sys
Worker_04       3143064 idle            1.2 GiB         3876 (0)        103856 (0)      NTFS:\hiberfil.sys
Worker_05       3143068 idle            1.2 GiB         1985 (0)        64947 (0)       NTFS:\WINDOWS\security
Worker_06       3143072 idle            1.2 GiB         4267 (0)        66089 (0)       NTFS:\WINDOWS\ServicePackFiles

Processing completed.
```

The status window includes information, such as:

* how many workers were started up;
* what the process identifier (PID) of the worker processes are;
* how many events in total and each one of the workers has extracted;
* what the last file entry was a worker was extracting events from.

The input in the previous example was a storage media image with a single
partition, which was running a Windows XP system on it. The first thing the
log2timeline.py does is to scan the storage media file, if it discovers more
than a single partition, an encrypted partition or that the partition contains
Volume Shadow Copies (VSS) it will ask the user for further details, for
example:

```bash
$ log2timeline.py --storage-file timeline.plaso bde_enabled_windows.dd

The following partitions were found:
Identifier      Offset (in bytes)       Size (in bytes)
p1              1048576 (0x00100000)    350.0MiB / 367.0MB (367001600 B)
p2              368050176 (0x15f00000)  148.7GiB / 159.7GB[PII_REDACTED]00 B)

Please specify the identifier of the partition that should be processed.
All partitions can be defined as: "all". Note that you can abort with Ctrl^C.
p2

Found a BitLocker encrypted volume.
Supported credentials:

  0. startup_key
  1. recovery_password
  2. password
  3. skip

Note that you can abort with Ctrl^C.

Select a credential to unlock the volume:
```

Note that there are various options that can be used to prevent
log2timeline.py from prompting the user to select VSS stores or
partitions.

* **--partitions PARTITION_NUMBERS**: Preselects the partition number to use, eg: `---partitions 2` will pick the second partition on the disk.
* **--vss_stores**: Selects the VSS stores to include, eg: `---vss_stores all` will select all available VSS stores, or `--vss_stores 1,4,5` (only first, fourth and fifth), or `--vss_stores 1..3` (first three stores) or `--vss_stores=none` will ignore available VSS stores.
* **--unattended**: log2timeline.py will error instead of prompting the user.

After finding a partition to process log2timeline.py will start the
pre-processing stage, where it collects information from the storage media.
That is evident by the entries like:

```bash
2015-07-16 16:54:05,368 [INFO] (MainProcess) PID:98252 <interface> [PreProcess] Set attribute: hostname to N-1A9ODN6ZXK4LQ
```

Here log2timeline.py detected that the hostname from the Windows installation
in this partition is: **N-1A9ODN6ZXK4LQ**.

Note that the pre-processing will also determine the most appropriate [parser preset](Parsers-and-plugins.md#parser-presets-plaso-data-presets-yaml).
The parser preset defines which parser are enabled. The auto-detection can be
overwritten with the `--parsers` option.

Note that for the `--parsers` option parser plugins need to be prefixed with
the name of their parent e.g. "winiis" should be specified as "text/winiis".

For more information about parsers and preset selection see: [Internals](../developer/Internals.md).

After that the tool spins up several workers (the actual number differs depends
on number of CPU's on the system running the tool), a collector and a storage
process.

## The info option

The first option is the `--info` which prints out information about all
supported plugins, parsers, output modules, etc.

```bash
$ log2timeline.py --info
======================== log2timeline/plaso information ========================

******************************** Parser Presets ********************************
                  android : android_app_usage, android_calls, android_sms
                    linux : bencode, filestat, google_drive, java_idx, olecf,
                            openxml, pls_recall, popularity_contest, selinux,
                            skype, syslog, utmp, webhist, xchatlog,
                            xchatscrollback, zeitgeist
                   macosx : appusage, asl_log, bencode, bsm_log,