How to Use Timesketch: A Beginner's Guide (First Install, First Sketch, First Timeline, and the Plaso Lesson)

CodexFuse Team · 2026-11-01T20:44:49.854Z · 14 min read min read

Learn how to use Timesketch: install it with Docker, create your first sketch, generate a timeline with Plaso, upload it, run an analyzer, and search like a DFIR analyst.

If you work in incident response, the worst part of a case is rarely the analysis. It is the chaos: a browser history export on one machine, Windows event logs on another, firewall logs on a third, and no single place where they all line up in time. This how to use Timesketch guide fixes that. Timesketch is Google's free, open-source platform for collaborative Timesketch timeline analysis, and this Timesketch tutorial takes you from zero to your first shared investigation: install it with Docker, create your first sketch, generate a timeline with Plaso, upload it, run your first analyzer, and search across everything like a working analyst.

What Is Timesketch, Exactly?

Timesketch is a free, open-source digital forensics timeline tool that lets one analyst, or a whole team, combine forensic timelines from many sources and analyze them together in one web interface. One sketch is usually one case: each sketch can hold multiple timelines, and analysts search across them, leave comments on individual events, and write stories that turn findings into a report-ready narrative.

The one thing beginners must understand before touching the install button: Timesketch does not acquire or parse evidence itself. Other tools — Plaso, Dissect, Velociraptor — generate timelines from disk images, logs, and endpoints. Timesketch is where you analyze them. The official developer docs say it plainly: "Timesketch is not a parser, and does not intend to be a parser. If you need to parse the data, you'll need other tools or libraries. Parsers can be implemented using plaso." Generate, then analyze. That division is the heart of the whole Timesketch workflow, and it never changes.

If your job starts earlier in the pipeline — watching live systems and collecting alerts rather than reconstructing what happened after the fact — that is the SIEM lane, and our Wazuh beginner guide covers it. Wazuh watches. Timesketch reconstructs.

Timesketch vs Plaso: The Generator-vs-Analyzer Line

The most common beginner confusion is treating Timesketch and Plaso as alternatives. They are not. They are two halves of one pipeline, and the difference matters because you cannot use Timesketch well until you understand which half does what.

The practitioner shorthand for the whole chain is: Velociraptor acquires, Plaso processes, Timesketch analyzes. Say it once, remember it always, and you will never upload a disk image to Timesketch wondering why it refuses to parse it.

What You Need Before Installing Timesketch

The official install guide is explicit: the preferred — and only tested and actively maintained — way to install Timesketch is with the provided Docker images. If you have not run a multi-container app before, read our Docker beginner guide first; the install below assumes you can run docker compose on a Linux host. The documented prerequisites are Ubuntu 22.04 and at least 8 GB of RAM, with the honest note that more is better. An optional domain name is needed only if you want SSL.

For a machine to run it on, you need a Linux server or a beefy lab VM. Our what is VPS hosting guide explains your options if you do not have one yet. Wherever you run it, size the disk for the evidence: the OpenSearch index and the PostgreSQL database both live under Timesketch's data directory, and forensic timelines grow fast. The official docs give no fixed disk figure, so use the practitioner's rule of thumb — at least as much free disk as the total size of the timelines you plan to upload, ideally several times more.

How Do I Install Timesketch with Docker?

This is the current official arc, verified against the Timesketch install docs in this writing session (it installs Timesketch web and API, the importer and analysis workers, PostgreSQL, a single-node OpenSearch cluster, Redis, and Nginx in one compose stack):

1. Download the deployment script: curl -s -O https://raw.githubusercontent.com/google/timesketch/master/contrib/deploy_timesketch.sh
2. Make it executable and move to /opt: chmod 755 deploy_timesketch.sh then cd /opt
3. Run it as root: sudo ./deploy_timesketch.sh
4. Enter the new directory and start the stack: cd timesketch then sudo docker compose up -d
5. Create your first user: sudo docker compose exec timesketch-web tsctl create-user <USERNAME>

curl -s -O https://raw.githubusercontent.com/google/timesketch/master/contrib/deploy_timesketch.sh
chmod 755 deploy_timesketch.sh
cd /opt
sudo ./deploy_timesketch.sh
cd timesketch
sudo docker compose up -d
sudo docker compose exec timesketch-web tsctl create-user analyst1

Two traps to avoid. First, the widely copied timesketch/timesketch login you see in blog posts is specific to the DS4N6 lab distro, not the official Docker deployment — the official flow has no default credentials; you create your own user with tsctl. Second, the data directory (default /opt/timesketch) is where OpenSearch and PostgreSQL store everything, so that disk needs the headroom discussed above. At the time of writing, the latest release was 20251114 (a November 2025 stability hotfix), and the project ships under the Apache 2.0 license, free for commercial and non-commercial use.

How Do I Create My First Sketch?

Log into the web UI and create your Timesketch sketch. The sketch lesson is short but foundational: a sketch is the investigation container — one sketch is usually one case. Every sketch can hold multiple timelines and multiple saved views, and it is the unit of sharing: you share sketches, not timelines.

Give the sketch a case-style name (an incident ticket number plus a short description works well), then open it. The sketch interface has five tabs, and beginners should learn what each is for before uploading anything: Overview is the case home page, Explore is where you search events, Stories is where findings become narrative, Attributes holds sketch-level metadata, and Intelligence curates indicators of compromise you want to pivot on. You do not need to fill any of them yet. The point of this step is only that the container exists and is empty, waiting for timelines.

How Do I Generate a Timeline to Analyze?

This is the Plaso lesson, and it is the step most "timesketch tutorial" searches skip. Timesketch analyzes timelines; Plaso builds them. The Timesketch Plaso handoff happens on the machine that holds your evidence (a disk image, a memory image, or a folder of logs), Plaso's log2timeline.py extracts every timestamped event it can find and writes a Plaso storage file. Then psort.py sorts, filters, and exports that file into a format Timesketch can read.

# 1. Extract events from evidence into a Plaso storage file
log2timeline.py timeline.plaso /mnt/evidence/

# 2. Export a CSV Timesketch can ingest
psort.py -w timeline.csv -o l2tcsv timeline.plaso

# 3. Inspect a storage file before exporting
pinfo.py timeline.plaso

The l2tcsv output module writes a CSV with 17 fixed fields that Timesketch understands directly. Alternatives in the psort toolbox: json_line for JSONL output and opensearch_ts, which is built specifically for Timesketch ingestion. If you want extraction and export in a single step, Plaso ships psteal.py, which runs log2timeline and psort together. The result of all of this is what practitioners call a super-timeline: one unified chronological view combining timestamps from every artifact source.

How Do I Upload a Timeline to Timesketch?

You have three ways to get a timeline into a sketch, and beginners should pick the Web UI first and graduate to the CLI when uploads become routine:

The CLI is worth learning because of its flags: --sketch-name picks the destination, --sketch-strategy newest|oldest|ask resolves name collisions, and --plaso-event-filter 'data_type is "fs:stat"' uploads only a slice of a storage file. If you roll your own CSV instead of using Plaso output, it must carry three mandatory fields — message (an informative string describing the event), datetime in ISO8601 (for example 2015-07-24T19:01:01+00:00), and timestamp_desc (for example "file created") — and the file name must end in .csv or .jsonl. If your columns are named differently, the upload UI offers a headers mapping step to match them up.

datetime,message,timestamp_desc,source
2026-10-31T08:14:02+00:00,User analyst1 logged on via RDP from 192.0.2.44,logon event,Security.evtx
2026-10-31T08:15:47+00:00,Outbound connection to suspicious-domain.example on port 443,network connection,firewall.log

How Do I Run an Analyzer in Timesketch?

Analyzers are where Timesketch starts doing work for you. Timesketch analyzers can auto-run on every new timeline added to a sketch, or you can trigger them manually from the Analyzer tab after a timeline finishes indexing. Analyzers can tag events, star them, leave comments, create saved views, add attributes, and even write stories — they are enrichment plus automation in one.

The shipped analyzer set is broad rather than fixed — the docs confirm browser_search, browser_timeframe, chain, domain, the Windows EVTX sessionizer and EVTX gap analyzer, safebrowsing, sigma, yeti_indicators, feature_extraction, tagger, similarity_scorer, login, and the ssh and web sessionizers, among others — so check the Analyzer tab in your own install for the current list rather than trusting any article's copy. Here is the beginner walkthrough using one of the most instructive ones:

1. Upload a timeline that contains browser history (a Plaso-processed user profile works).
2. Open the sketch and switch to the Analyzer tab.
3. Select the timeline, find browser_search, and run it.
4. The analyzer scans events for URLs that look like search-engine queries and extracts the search strings.
5. Read the story it writes: the top 20 most common discovered searches, the domains used to search, the most common days of searching, and an overview of all discovered search terms.

Two gotchas before you run more: the safebrowsing analyzer needs a SAFEBROWSING_API_KEY set in timesketch.conf before it can enrich anything, and the feature_extraction and tagger analyzers read their rules from data/regex_features.yaml and data/tags.yaml — edit those files to teach Timesketch what to look for in your environment.

How Do I Search Across Timelines in Timesketch?

All timeline data in Timesketch is stored in OpenSearch, and the Explore tab is a search box over that index. Every event carries four always-present fields you can rely on in every query:

Plaso-generated timelines add more searchable fields like data_type and filename. Queries use the OpenSearch query-string mini-language: AND, OR, NOT, ? and * wildcards, and /regex/ patterns. Recent releases added a Wildcard Search Mode toggle for case-insensitive substring search — *evil* or message:*evil* finds anything containing the string. The workflow that scales: run a query, click Save under the query field to keep it as a saved search, and reuse the Search templates dropdown for quick-start views. To prune noise without deleting evidence, hide individual events with the eye icon.

Searching is also the skill that turns a timeline from a pile of events into an investigation: pivot from a suspicious IP in one timeline to every event mentioning it across all timelines in the sketch, then save that view so the whole team works from the same slice, and that collaborative pivoting is what separates Timesketch timeline analysis from plain log search.

How Do I Share and Collaborate in Timesketch?

A sketch becomes a team workspace in one step: share it with individual users, with groups of users, with everyone on the system, or keep it private. Comments attach to events and are saved per sketch — the same timeline opened in two sketches shows a comment only in the sketch where it was made, which keeps each case's discussion separate.

When findings start to form a narrative, use Stories: markdown text interleaved with saved views and aggregations, written for the report reader rather than the analyst. The Intelligence tab is the third collaboration surface — it curates indicators of compromise, with a pencil to edit them and a magnifier to pivot straight into a search. If your workflow also needs the case-management half of incident response — assigning tasks, tracking alert triage, running playbooks — that is a different lane from timeline analysis: our TheHive beginner guide covers it. TheHive manages cases. Timesketch builds timelines.

Seven Beginner Mistakes with Timesketch

Sources

• Timesketch install guide (Docker, prerequisites, deploy_timesketch.sh arc, tsctl create-user): https://timesketch.org/guides/admin/install/
• Timesketch user guide — basic concepts (sketch as case, sketch tabs): https://timesketch.org/guides/user/basic-concepts/
• Timesketch user guide — sketch overview (sharing, comments per sketch, stories, intelligence tab): https://timesketch.org/guides/user/sketch-overview/
• Timesketch user guide — upload data (Plaso/CSV/JSONL formats, importer CLI flags, web UI): https://timesketch.org/guides/user/upload-data/
• Timesketch user guide — import from CSV/JSON (mandatory message/datetime/timestamp_desc fields, headers mapping): https://timesketch.org/guides/user/import-from-json-csv/
• Timesketch user guide — search query guide (OpenSearch backend, query-string syntax, saved searches, Wildcard Search Mode): https://timesketch.org/guides/user/search-query-guide/
• Timesketch analyzer development docs (shipped analyzer list, analyzer capabilities): https://timesketch.org/developers/analyzer-development/
• Timesketch API upload-data developer docs ("Timesketch is not a parser", ImportStreamer): https://timesketch.org/developers/api-upload-data/
• Timesketch CLI client docs (sessionizer/login analyzers): https://timesketch.org/guides/user/cli-client/
• Timesketch GitHub releases (20251114 release, Apache 2.0 license): https://github.com/google/timesketch/releases and https://github.com/google/timesketch
• Plaso documentation — log2timeline output and psort formatting (l2tcsv 17 fields, json_line, opensearch_ts): https://plaso.readthedocs.io/en/latest/sources/user/Output-and-formatting.html
• Plaso documentation — storage files (single storage mechanism, psort post-processing): https://plaso.readthedocs.io/en/stable/sources/user/Log2Timeline-Perl-%28Legacy%29.html
• DeepWiki Timesketch Docker deployment (config.env NGINX_HTTP_PORT/HTTPS_PORT defaults): https://deepwiki.com/google/timesketch/7.1-docker-deployment
• DS4N6 Timesketch guide (distro-specific timesketch/timesketch creds — not official): https://ds4n6.io/blog/21051703.html
• Zawadidone — scalable forensics timeline analysis with Dissect and Timesketch (Velociraptor → Plaso → Timesketch pipeline): https://zawadidone.nl/scalable-forensics-timeline-analysis-using-dissect-and-timesketch/

Frequently Asked Questions

Is Timesketch free?

Yes. Timesketch is open source under the Apache 2.0 license, free for commercial and non-commercial use, and there is no paid edition of the platform itself. Your only costs are the server you run it on and the time you spend feeding it timelines.

What is the difference between Timesketch and Plaso?

Plaso generates timelines and Timesketch analyzes them. Plaso's log2timeline extracts events from evidence into a storage file and psort exports it as CSV or JSONL; Timesketch ingests those files into a searchable, collaborative interface. They are complementary halves of one DFIR pipeline, not alternatives.

Can Timesketch analyze a disk image directly?

No. Timesketch is not a parser and does not acquire evidence itself. Process the image with Plaso (or Dissect, or Velociraptor) first, then upload the resulting timeline file. The official developer documentation states this explicitly.

What are the Timesketch default login credentials?

There are none in the official Docker deployment — you create the first user yourself with sudo docker compose exec timesketch-web tsctl create-user <USERNAME>. The timesketch/timesketch credentials you see in tutorials belong to the DS4N6 lab distro, not the official install.

How much RAM and disk does Timesketch need?

The official install guide asks for Ubuntu 22.04 and at least 8 GB of RAM, more if you can spare it. Disk space is driven by your evidence: OpenSearch and PostgreSQL data live under /opt/timesketch by default, so keep free disk several times larger than the total size of the timelines you plan to upload.