# Super timeline builder

Merge parsed forensic artifact CSVs into one sorted UTC timeline with expansion, dedupe, filters, and CSV/l2tcsv/TLN exports.

## Run it

- **CLI:** `gizza tool super-timeline-builder '--- mft ---
Path,Created,LastModified
\Users\a\evil.exe,2024-06-01 10:00:05,2024-06-01 10:00:09
=== evtx ===
TimeCreated,EventID,Computer
2024-06-01 10:00:01,4624,DC01'`
- **Web:** https://gizza.ai/tools/super-timeline-builder/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/super-timeline-builder/tool.json

## Inputs

- `artifacts` — Artifact CSV sections _(field)_
- `format` — Output format _(field)_
- `order` — Sort order _(field)_
- `expand` — Expand timestamp columns _(field)_
- `dedupe` — Remove duplicate events _(field)_
- `from` — From _(field)_
- `to` — To _(field)_
- `tz_offset` — Naive timezone offset (hours) _(field)_
- `drop_epoch_zero` — Drop 1970-01-01 zero timestamps _(field)_
- `delimiter` — Delimiter _(field)_
- `limit` — Row limit _(field)_

## Output

- Merged timeline (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `artifacts` — Artifact CSV sections
- `format` — Output format
- `order` — Sort order
- `expand` — Expand timestamp columns
- `dedupe` — Remove duplicate events
- `from` — From
- `to` — To
- `tz_offset` — Naive timezone offset (hours)
- `drop_epoch_zero` — Drop 1970-01-01 zero timestamps
- `delimiter` — Delimiter
- `limit` — Row limit

Example: `https://gizza.ai/tools/super-timeline-builder/?artifacts=---%20mft%20---%0APath%2CCreated%2CLastModified%0A%5CUsers%5Ca%5Cevil.exe%2C2024-06-01%2010%3A00%3A05%2C2024-06-01%2010%3A00%3A09%0A%3D%3D%3D%20evtx%20%3D%3D%3D%0ATimeCreated%2CEventID%2CComputer%0A2024-06-01%2010%3A00%3A01%2C4624%2CDC01&format=csv&order=asc&expand=true&dedupe=true&from=2024-06-01T00%3A00%3A00Z&to=2024-06-02T23%3A59%3A59Z&tz_offset=0&drop_epoch_zero=true&delimiter=auto&limit=10000`

---

## About this tool

Build a single super-timeline from CSVs that have already been parsed from forensic artifacts. Paste
one table after another and introduce each table with a source header such as `--- mft ---`,
`=== evtx ===`, `==> prefetch <==`, or `# browser-history`. Each section keeps its own header row and
delimiter.

Worked example:

```csv
--- mft ---
Path,Created,LastModified
\Users\a\evil.exe,2024-06-01 10:00:05,2024-06-01 10:00:09
=== evtx ===
TimeCreated,EventID,Computer
2024-06-01 10:00:01,4624,DC01
```

With the default compact CSV output, the event-log row sorts first, followed by the MFT Created and
LastModified events. The default `expand=true` emits one event per timestamp column, which is useful
for file-system rows that carry created, modified, changed, and accessed times.

Limits and edge cases: this tool merges parsed CSVs only; it does not parse raw MFT, EVTX, browser
database, or registry hive files. Input is capped at 200,000 lines and output at the `limit` value
(max 100,000 rows). Timezone-less timestamps use `tz_offset`; timestamps that already contain `Z` or
an explicit offset keep their own offset and are normalized to UTC.

## FAQ

<details>
<summary>What should I paste into the input?</summary>

Paste CSV exports from tools that already parsed the artifact, such as an MFT listing, event-log CSV,
prefetch table, browser-history export, or registry report. Put a source header before each table so
rows can be traced back to the artifact that produced them.

</details>

<details>
<summary>Why does one input row become several timeline rows?</summary>

When `expand` is on, each timestamp column becomes its own event. For example, one file row with
Created and LastModified values becomes two timeline rows labelled with those column names. Turn
`expand` off if you only want the first detected timestamp column from each section.

</details>

<details>
<summary>Which output format should I choose?</summary>

Use `csv` for a compact `datetime,timestamp_desc,source,message` table. Use `l2tcsv` when you need the
legacy 17-field log2timeline-style layout for timeline viewers. Use `tln` for pipe-delimited
`Time|Source|Host|User|Description` rows with epoch-second timestamps.

</details>

<details>
<summary>How are timezones handled?</summary>

Timestamps with `Z` or an explicit `+/-hh:mm` offset are normalized directly to UTC. Naive timestamps
without a timezone use the `tz_offset` setting, so `tz_offset = -5` treats `2024-06-01 12:00:00` as
noon in UTC-05:00 and outputs `17:00:00Z`.

</details>

## Related tools

- [CSV timeline viewer](https://gizza.ai/tools/csv-timeline-viewer/): Paste a CSV, TSV or JSON Lines event log and filter it by time range, search every column, sort, pick columns and page through the matches locally.
- [ARFF Converter](https://gizza.ai/tools/arff-converter/): Convert Weka ARFF datasets to CSV and CSV tables back to ARFF locally — nominal attributes, numeric types, dates, sparse rows, missing values, and type rows.
- [Beancount to CSV Converter](https://gizza.ai/tools/beancount-to-csv/): Flatten Beancount or Ledger journal postings into spreadsheet-ready CSV, then rebuild a simple journal from that flat CSV schema.
- [Cartesian to polar CSV converter](https://gizza.ai/tools/cartesian-to-polar-csv/): Convert a whole CSV of (x, y) points to polar (r, θ) coordinates in your browser, in degrees or radians, keeping your other columns intact.
- [CSV Cell Diff](https://gizza.ai/tools/csv-cell-diff/): Compare two CSVs column-by-column and highlight every individual cell that changed, plus added and removed rows and columns.