Timesketch Guide: Collaborative Forensic Timelines

Once an investigation spans more than one host or more than one analyst, a timeline held in a spreadsheet or a single analyst's terminal stops scaling, and findings, comments and context get lost between people. Timesketch is an open source, Apache 2.0 licensed web application from the Google-owned OSDFIR project for collaborative forensic timeline analysis: it indexes events from Plaso, CSV and JSONL into OpenSearch and lets a team search, tag, comment, run analyzers and write up findings in a shared case called a sketch. This guide covers what the tool does, where it helps defenders, how to deploy it without turning your evidence store into a liability, and how to measure whether it is working. It is for DFIR leads, incident responders and platform engineers who run the server. Building the timeline itself is covered in the Plaso Guide, and the method in the Forensic Timeline Analysis Guide; this page is about the analysis platform.

This is an independent guide from NHI Mgmt Group, based on Google's public documentation as of November 2026. It is not sponsored or reviewed by Google. Product features change, so confirm settings against Google's current documentation.

Key takeaways

Timesketch is the analysis layer, not the collector. It ingests Plaso storage files, CSV and JSONL; parsing disks and logs still happens upstream in tools such as Plaso, Hayabusa or Velociraptor.
The sketch is the unit of work and of access. One sketch is usually one case, holding several timelines, saved views, stories and comments, shared with named users, groups or everyone.
It concentrates sensitive evidence. An instance holds credentials, personal data and attacker activity from every case, so it needs the same identity, network and logging controls as any evidence store.
Defaults are built for a lab. The sample configuration ships with a placeholder SECRET_KEY, OpenSearch TLS off and uploads disabled, and if both OIDC allow lists are empty every authenticated user may log in.
Analyzers and Sigma speed triage but need curation. The project itself warns against loading the whole SigmaHQ repository and treats Sigma support as alpha.

What the tool does

Timesketch runs as a set of containers. The official install guide states that Docker is the preferred and the only tested and actively maintained installation method, on Ubuntu 22.04 with at least 8 GB of RAM. The deployment script deploy_timesketch.sh sets up six services:

Component	Role	Security relevance
Timesketch web and API server	User interface, REST API, authentication	The only service that should face analysts; put it behind TLS
Importer and analysis worker (Celery)	Parses uploads, runs analyzers, Sigma jobs	Processes untrusted evidence files; isolate and patch it
PostgreSQL	Sketches, users, groups, ACLs, comments, stories	Holds case metadata and access control; back it up and restrict it
OpenSearch (single node by default)	Event indices and search	Holds the raw evidence; never expose it beyond the Timesketch hosts
Redis	Task queue for workers	Internal only
Nginx	Reverse proxy and TLS termination	Where certificates and HTTPS redirect live

Inside the application, the concepts that matter are:

Sketch: a case workspace with five tabs: Overview, Explore, Stories, Attributes and Intelligence.
Timeline: one imported data source. The same timeline can be added to several sketches; comments stay in the sketch where they were made.
View: a saved search, created by a user, by the API or by an analyzer.
Tags, stars and comments: tags are stored on the event in the OpenSearch field tag, so upstream tools can set them at parse time. The older database-held labels are being phased out.
Stories: narrative write-ups that embed saved views, starred events and aggregations, which is where a report starts.
Insights: terms and filtered terms aggregations rendered as tables or charts, for example a count by data_type.
Search history: a branching tree of every query in the sketch, which doubles as a record of how the analysis was done.

For CSV and JSONL imports three fields are mandatory: message, datetime (ISO 8601, for example 2015-07-24T19:01:01+00:00) and timestamp_desc. Missing fields can be mapped from existing columns in the upload dialogue. Files must end in .csv or .jsonl; JSONL is streamed and uses far less memory. OpenSearch rejects keyword values above 32,766 bytes, so Timesketch indexes oversized fields as text only, which means they can be searched but not aggregated or sorted.

Defender use cases

Use case	How Timesketch helps	Typical inputs
Multi-host intrusion investigation	Several timelines in one sketch, searched together and correlated by time	Plaso files per host, EDR exports as JSONL
Identity compromise and lateral movement	The `login` analyzer marks Windows logon and logoff events, `ssh_sessionizer` groups SSH sessions by client IP and port, `account_finder` surfaces accounts	Windows event logs, Linux auth logs
Anti-forensics checks	`ntfs_timestomp` compares NTFS $STANDARD_INFORMATION and $FILE_NAME timestamps; `win_evtxgap` looks for gaps in event logs	Plaso output from disk images
Cloud and service account activity	`gcp_servicekey` extracts Compute Engine actions from Google Cloud logging	Cloud audit logs as JSONL
Detection rule retro-hunting	Sigma rules run as analyzers or in the Sigma studio against historical events	Any normalised log timeline
Structured investigations	DFIQ (Digital Forensics Investigative Questions) templates, loaded from disk or a YETI instance, give a question-led approach	DFIQ YAML
Handover and reporting	Stories, saved views and comments give one shared record for responders, legal and management	Analyst findings

Where identity fits: most intrusions now run through valid accounts, service principals and API keys, so a large part of timeline work is following a credential across hosts and cloud logs. Tag every event that involves a machine credential so the story shows when a key was first used, from where and what it touched. The Identity Threat Hunting Guide covers the hypotheses worth running.

Deployment and safe use

Treat a Timesketch instance as a forensic evidence system. A phased rollout:

Decide the boundary. One instance per legal entity or classification level is simpler than relying on sketch ACLs to separate cases that must never mix. Record data residency and retention rules before the first upload.
Build from the official Docker deployment. Pin image versions, keep the data directory on encrypted storage sized for OpenSearch and PostgreSQL growth, and replace the placeholder SECRET_KEY and database passwords with generated secrets held in a secrets manager.
Turn on TLS everywhere. Terminate HTTPS at Nginx with a redirect from HTTP (the install guide shows a certbot pattern). Inside the stack, set OPENSEARCH_SSL = True with OPENSEARCH_VERIFY_CERTS = True and an OpenSearch user rather than anonymous access. The Elasticsearch and OpenSearch Security Guide covers the cluster side.
Use a dedicated OpenSearch service account. Set OPENSEARCH_INDEX_PREFIX (for example timesketch-) before first start and restrict the account to that index pattern. The prefix applies only to new indices, so setting it later and then tightening permissions makes old indices unreadable; tsctl info warns about unprefixed indices.
Connect single sign-on. Enable OIDC (GOOGLE_OIDC_ENABLED, despite the name it works with other providers via GOOGLE_OIDC_AUTH_URL and GOOGLE_OIDC_DISCOVERY_URL). Set GOOGLE_OIDC_GROUPS_CLAIM, GOOGLE_OIDC_ALLOWED_GROUPS, GOOGLE_OIDC_ADMIN_GROUP, GOOGLE_OIDC_GROUPS_SYNC_ENABLED and GOOGLE_OIDC_GROUPS_REMOVE_STALE so access follows your IdP. Never leave both allow lists empty.
Govern non-human access. Automated importers authenticate with auth_mode = userpass only if listed in LOCAL_AUTH_ALLOWED_USERS; keep that list short, named per pipeline, and rotate the passwords. The importer stores credentials in ~/.timesketchrc and an encrypted token file, so run it from controlled hosts, not analyst laptops.
Pilot with one closed case. Import a known dataset, run the analyzers you plan to auto-run (AUTO_SKETCH_ANALYZERS), check counts against the source and confirm sharing behaves as expected.
Define retention and closure. Archive closed sketches (indices are closed, nothing can be explored), apply the protected or preserved label to sketches under legal hold, and reserve hard delete, which is admin only and permanently removes indices, for the end of the retention period.

Rollback: upgrades follow the project upgrade guide; snapshot PostgreSQL and OpenSearch before every upgrade, because a failed schema migration otherwise strands sketch metadata from its indices.

Access control traps

Browser and API logins differ: group checks and sync only apply to the browser login at /login/google_openid_connect/. The API client login is a separate Google-only flow governed by GOOGLE_OIDC_API_CLIENT_IDS and GOOGLE_OIDC_ALLOWED_USERS. Test both.
Group sync happens at login only: removing someone in the IdP does not end an existing session. Pair deprovisioning with session revocation or a short session lifetime.
Admins see everything: administrators can delete any sketch regardless of its ACL. Keep the admin group to platform owners and log its use.
Sharing with all users: a sketch can be made available to every user on the system. Set a rule on when that is acceptable, and review shared sketches monthly.

Large language model features

Recent releases include experimental LLM features (event summarisation and natural language to query) configured through LLM_PROVIDER_CONFIGS. Sending case events to an external model is a data transfer: approve the provider under your data protection rules, prefer a provider and region you already contract with, and keep the features off on instances holding regulated data until that is done.

Detection and hardening value

Timesketch improves detection in two ways: it shortens triage on a live case, and it turns findings into reusable searches and rules. Saved views and Sigma rules written during one case become the starting point of the next; the Sigma Rules Guide covers rule quality. Only Sigma rules with status stable are used by the Sigma analyzer, rules that use aggregations are not supported by the OpenSearch backend, and the project advises deploying only rules whose log formats you have verified.

Monitor the platform itself as an evidence system:

Authentication logs: denied OIDC logins are logged with the user and claim presence; alert on repeated denials and on any local userpass login from an account not on the pipeline list.
Privilege changes: new admins, new groups and sketches shared with all users.
Destructive actions: soft and hard deletes, archive and unarchive.
Worker health: failed imports and analyzer errors in Celery logs, which silently leave gaps in a timeline.
Capacity: OpenSearch allows a maximum of 1,500 open shards in the documented design, and the project warns that a timeline with more than 150 indices makes sketch searches impossible.

Metric	What it shows	Target direction
Time from evidence receipt to searchable timeline	Pipeline speed	Hours, falling
Import failure rate	Silent evidence gaps	Near zero, every failure explained
Cases closed with a story attached	Reporting discipline	100%
Sketches shared with all users	Access hygiene	Low, each justified
Saved views or Sigma rules promoted to production detection per quarter	Learning loop from IR to SOC	Rising
Closed sketches not archived after retention review	Retention control	Zero

Framework mapping

Framework	Reference	How Timesketch supports it
NIST CSF 2.0	RS.AN-03	Establishing what took place and the root cause across sources
NIST CSF 2.0	RS.AN-06	Search history, comments and stories record investigation actions; protect their integrity
NIST CSF 2.0	DE.AE-02	Analysing adverse events with analyzers and Sigma
NIST SP 800-53 Rev. 5	IR-4, AU-6	Incident handling and audit record analysis
NIST SP 800-53 Rev. 5	AU-9, AU-11	Protecting and retaining the evidence the platform holds
NIST SP 800-53 Rev. 5	AC-3, IA-2, SC-8	Sketch ACLs, SSO and TLS for the platform itself

Common failure patterns

OpenSearch reachable from the network: the evidence index is the asset; a cluster open beyond the Timesketch hosts bypasses every sketch ACL.
Time zone confusion: CSV imports with local times and no offset produce plausible but wrong sequences. The project recommends its OSDFIR posts on time pitfalls before the first case for this reason.
Loading every Sigma rule: parse errors and noisy hits bury the useful results; curate a tested subset.
Treating a failed import as done: a partial upload looks complete in the UI; reconcile event counts against the source.
Shared pipeline credentials: one userpass account used by every importer cannot be traced or revoked cleanly.
No legal hold labels: without protected or preserved, routine clean-up can delete evidence still needed; see the Evidence Handling and Chain of Custody Guide.

Alternatives

Option	Best when	Trade-off against Timesketch
Plaso psort output in a spreadsheet or Timeline Explorer	One analyst, one host, small case	Suited to single-analyst work; add your own process for sharing and access control
Your SIEM or OpenSearch Dashboards	Logs already centralised, SOC-led case	Confirm how it handles disk artefacts and per-case isolation
Velociraptor notebooks	Live endpoint collection and hunting at scale	Focused on collection and hunting; pairs with a timeline tool for long-term multi-source timelines. See the Velociraptor Guide
Hayabusa or Chainsaw on event logs	Fast Windows event log triage	Command line output, often fed into Timesketch rather than replacing it. See the Hayabusa and Chainsaw Guide
Autopsy	Single-image disk examination	Desktop, examiner-centric rather than team timeline. See the Autopsy and The Sleuth Kit Guide

Small teams that handle a few cases a year may get more from a disciplined Plaso and spreadsheet process than from running another server. Teams with several responders, recurring cases or an outsourced partner gain most from Timesketch, because the shared sketch replaces email chains of findings. The wider tool set is mapped in the Open Source DFIR Tools Landscape Guide.

Practitioner checklist

Deploy with the official Docker method, pinned versions and encrypted storage.
Replace the placeholder SECRET_KEY and all default passwords with generated secrets.
Enforce HTTPS at Nginx and TLS with certificate verification to OpenSearch.
Set OPENSEARCH_INDEX_PREFIX before first start and restrict the service account to it.
Enable OIDC with an allowed group and admin group; test both browser and API client logins.
Keep LOCAL_AUTH_ALLOWED_USERS to named pipeline accounts and rotate their passwords.
Curate Sigma rules and auto-run analyzers on a pilot case before production use.
Reconcile imported event counts with the source for every timeline.
Label legal hold sketches protected or preserved; archive closed cases; log every hard delete.
Approve any LLM provider under data protection rules before enabling LLM features.

Standards and references

Related NHI Mgmt Group resources: Plaso Guide · Forensic Timeline Analysis Guide · Digital Forensics (DFIR) Guide · Incident Response Guide

Timesketch: Deploy, Secure and Run Collaborative Forensic Timelines