Log2timeline timeline generation: Using psort

# Using psort.py (Plaso Síar Og Raðar Þessu)

**psort** is a command line tool to post-process Plaso storage files. It allows
you to filter, sort and run automatic analysis on the contents of Plaso storage
files.

Looking for [tips and tricks](Using-psort.md#how-do-i)?

## Usage

To see a list of all available parameters you can pass to psort use ``-h`` or
``--help``.

The most basic way to use **psort** is to provide it with a storage file and
output file, for example:

```bash
$ psort.py -w test.log timeline.plaso
```

This will use the default dynamic output format and write to test.log all
extracted events, merging detected duplicate events. All date and time values
will be in UTC.

**Note that as of 1.5.0 psort no longer supports writing output to stdout.**

Some other basic options are:

```bash
$ psort.py [-a] [-o FORMAT] [-w OUTPUTFILE] [--output-time-zone TIME_ZONE] STORAGE_FILE FILTER
```

### Output format

**psort** uses output modules to output in different formats. To see a list of
the available supported output modules use the ``-o list`` parameter, for example:

```bash
$ psort.py -o list

******************************** Output Modules ********************************
      dynamic : Dynamic selection of fields for a separated value output
                format.
         json : Saves the events into a JSON format.
    json_line : Saves the events into a JSON line format.
          kml : Saves events with geography data into a KML format.
       l2tcsv : CSV format used by legacy log2timeline, with 17 fixed fields.
       l2ttln : Extended TLN 7 field | delimited output.
         null : Output module that does not output anything.
   opensearch : Saves the events into an OpenSearch database.
opensearch_ts : Saves the events into an OpenSearch database for use with
                Timesketch.
        rawpy : native (or "raw") Python output.
          tln : TLN 5 field | delimited output.
         xlsx : Excel Spreadsheet (XLSX) output
--------------------------------------------------------------------------------
```

If you are missing any optional dependencies not all output modules may be
available, which would be displayed by the ``-o list`` switch, for example:

```bash
******************************** Output Modules ********************************
     Name : Description
--------------------------------------------------------------------------------
  dynamic : Dynamic selection of fields for a separated value output format.
     json : Saves the events into a JSON format.
json_line : Saves the events into a JSON line format.
      kml : Saves events with geography data into a KML format.
   l2tcsv : CSV format used by legacy log2timeline, with 17 fixed fields.
   l2ttln : Extended TLN 7 field | delimited output.
     null : Output module that does not output anything.
    rawpy : native (or "raw") Python output.
      tln : TLN 5 field | delimited output.
     xlsx : Excel Spreadsheet (XLSX) output
--------------------------------------------------------------------------------

*************************** Disabled Output Modules ****************************
         Name : Description
--------------------------------------------------------------------------------
   opensearch : Saves the events into an OpenSearch database.
opensearch_ts : Saves the events into an OpenSearch database for use with
                Timesketch.
--------------------------------------------------------------------------------
```

Also see [output and formatting](Output-and-formatting.md).

#### Changing output format

To change the output use the ``-o FORMAT`` parameter, for example:

```bash
$ psort.py -o l2tcsv -w test.l2tcsv timeline.plaso
```

This would use the "l2tcsv" output module, which is the CSV output of the older
Perl version of log2timeline.

#### Modify the output time zone

**psort** uses UTC as its default time zone when outputting events. Some
output formats, like dynamic and l2tcsv can output date and time values in
a different time zone. This can be controlled using the
``--output-time-zone TIME_ZONE`` parameter, for example.

```bash
$ psort.py --output-time-zone EST5EDT timeline.plaso
```

To see a list of all supported time zones use the `--output-time-zone list`
parameter:

```bash
$ psort.py --output-time-zone list

************************************ Zones *************************************
                        Timezone : UTC Offset
                  Africa/Abidjan : +00:00
                    Africa/Accra : +00:00
              Africa/Addis_Ababa : +03:00
                  Africa/Algiers : +01:00
                   Africa/Asmara : +03:00
                   Africa/Asmera : +03:00
...
```

#### Quiet and More Verbose Output

**psort** records the number of events it processes and how many events got
filtered out due to filter settings or to duplication removals. This
information is printed out at the end of each run, for example:

```bash
$ psort.py timeline.plaso "SELECT timestamp LIMIT 10"
...
[INFO] Output processing is done.

*********************************** Counter ************************************
            Stored Events : 143960
          Events Included : 10
               Limited By : 10
```

Or from a full run:

```bash
$ psort.py timeline.plaso
...
*********************************** Counter ************************************
            Stored Events : 143960
          Events Included : 143812
       Duplicate Removals : 23157

```

This output provides valuable information about how many events got filtered
out by for instance the duplicate entry removals. There are many reasons why
there may be duplicate entries in an output:

+ A filesystem entry that has the same timestamp for MACB timestamps (or any combination of them)
+ Parsing a storage media file and processing a VSS store will produce a lot of duplicate entries, for example: the exact same Event Log record.
+ Metadata information extracted from a file that is stored in more than one place on the drive

If you don't want duplicate entries to be removed it is possible to supply the
flag ``-a`` or ``--include_all` to **psort**.

```bash
$ psort.py -a -w all_events.txt timeline.plaso
```

If you on the other hand do not want to see the overview printed at the end it
is possible to silence it with the ``-q`` flag:

```bash
$ psort.py -q -w output.csv timeline.plaso
```

### Automatic Analysis

Plaso defines a concept called an analysis plugin. Essentially that means that
you can write a plugin that gets a copy of every event that is extracted and is
not filtered out to inspect and potentially extract meaning or context out of.
This information can be used to create tags and attach them back to the events
or to create reports.

As of now the analysis plugins are only exposed to the post-processing layer,
as in exposed to **psort** although there are efforts underway to expose them
to the extraction stage as well. That way you can use them to create tags t