# Timesketch: collaborative forensic timeline analysis for DFIR teams

> Timesketch is a web application for organizing forensic timelines into sketches and annotating them with a team. It is aimed at incident responders who need shared, queryable timelines rather than one analyst's local spreadsheet.

**google/timesketch** — Collaborative forensic timeline analysis

- Repository: https://github.com/google/timesketch
- Stars: 3,427 · Forks: 669
- Language: Python
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-timesketch

## The problem Timesketch solves: one timeline, many analysts

Forensic timelines are large and they are usually reviewed by more than one person. The README describes Timesketch as "an open-source tool for collaborative forensic timeline analysis" and says that "using sketches you and your collaborators can easily organize your timelines and analyze them all at the same time." That sentence is the product definition. A sketch is the container: you put one or more timelines into it, and the people you share it with see the same events rather than a copy of your export.

The annotations are the second half of the idea. The README lists "rich annotations, comments, tags and stars" as the way to "add meaning to your raw data." In practice this means one analyst can tag a suspicious process execution, another can comment on it, and the tag survives in the sketch instead of living in a chat thread. The repository topics confirm the audience: analysis, dfir, forensics, security, timeline. This is incident response tooling, not a general log viewer.

## How Timesketch is put together: Flask, OpenSearch and Celery

The repository layout shows the shape of the system. timesketch/ holds the application, config/ holds configuration, docker/ holds container definitions, and there are three separate client directories: api_client/, cli_client/ and importer_client/. Those three are packaged independently, which is visible in the README badges: timesketch, timesketch_api_client and timesketch_import_client each have their own PyPI version.

The Python dependencies in requirements.txt name the moving parts. Flask==3.1.3 with flask_login, flask_restful, flask_sqlalchemy and flask_migrate is the web layer and its database migrations. opensearch-py==2.8.0 is the search backend where timeline events live. celery==5.4.0 with redis==4.4.4 handles background work such as import and analysis jobs. There is also a long list of OpenTelemetry packages plus prometheus-client and prometheus-flask-exporter, so instrumentation is built in rather than bolted on.

The analysis side leans on numpy, scipy, pandas, datasketch and networkx. datasketch is the interesting one for anyone doing near-duplicate detection across events, and networkx points at graph-style analysis over the same data. A google-genai dependency is present, which is consistent with the "timesketch ai" and "Timesketch LLM" searches around the project, though the README itself does not document those features and the user-facing guide is where they would be described.

## Installing Timesketch and running a first sketch

The README does not inline installation steps. It links to "Install Timesketch" under https://timesketch.org/guides/admin/install/, and that guide is the authoritative source. What the repository does tell you is that the stack is not a single binary: the docker/ directory exists for containerized deployment, and requirements.txt pins a web framework, a search engine client, a task queue and Redis. Expect to provision OpenSearch, Redis and a SQL database before the web app is useful.

The packaging files also set a floor on the runtime. setup.py exits with an error below Python 3.6, printing "Unsupported Python version: {0:s}, version 3.6 or higher required." That is a minimum, not a recommendation; the pinned Flask, SQLAlchemy and pandas versions in requirements.txt are far newer than that floor implies.

Once a server is running, the README points to "Upload data" at https://timesketch.org/guides/user/upload-data/ for adding timelines and to the users guide at https://timesketch.org/guides/user/basic-concepts/ for the workflow. If you would rather script it than use the UI, the importer client is the entry point:

```bash
pip install timesketch_import_client
```

The README badge for timesketch_import_client confirms it is published on PyPI under that name. The same is true of the API client and the CLI client, which the repository keeps in separate top-level directories:

```bash
pip install timesketch_api_client
```

For a notebook-based workflow, the README has a dedicated section, "Adding a Notebook Container," linking to https://timesketch.org/guides/user/notebook/. That is the documented path for running analysis code next to the sketch data rather than exporting events out of the system.

## Where Timesketch is the wrong tool

Timesketch does not parse evidence. The README never claims it does, and the related searches pairing "timesketch plaso" point at the real division of labour: Plaso produces the timeline, Timesketch stores, queries and annotates it. If your problem is getting events out of an image or a set of artifacts, Timesketch is downstream of that step, not a replacement for it.

The operational footprint is the second constraint. A Flask app, OpenSearch, Redis, Celery workers, a relational database and Alembic migrations is a service to run, back up and upgrade. A solo examiner working one case on a laptop gets little from the collaborative features and pays the full cost of the stack. The README's own fine print is worth reading before you promise anything to a stakeholder: "This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google." That is a support statement, not a technical one, and it matters when someone asks who stands behind the deployment.

Finally, the README does not document rollback, backup or restore procedures. The install guide is where an administrator would look for them, and the README is silent on the subject.

## Timesketch compared with Plaso and with a general log stack

The clearest alternative is Plaso, and the difference is architectural rather than cosmetic. Plaso is a parser: it runs against evidence and emits a timeline. Timesketch is a multi-user application that ingests those timelines and gives a team a shared place to query and annotate them. Choosing between them is not a choice at all for most DFIR work, since Plaso output is a natural input to Timesketch. The choice only appears when you have no need for the shared layer.

The other alternative is a general search stack built on OpenSearch or Elasticsearch directly. Timesketch already sits on opensearch-py, so the underlying storage is not the differentiator. What Timesketch adds is the forensic data model: sketches, timelines within sketches, tags, comments and stars, plus a REST API and a CLI so the same objects are reachable from a script. Rebuilding that on a bare index means writing the schema, the permission model and the UI yourself. Teams that only need to grep logs should not pay for it.

## Licence, releases and the cost of staying current

Timesketch is Apache-2.0, and the LICENSE file sits at the top level of the repository. The permissive terms matter here because the deployment includes a web application you may modify and internal services you may redistribute. This is a description of the licence text, not legal advice; if you are embedding Timesketch in a product, have counsel read the file.

The project ships frequently. The recent release tags are 20260611, 20260617 and 20260630, all within June 2026, and the last push to master was on 2026-09-08. That cadence is the upgrade cost: pinned dependencies in requirements.txt such as Flask 3.1.3, SQLAlchemy 1.4.54 and opensearch-py 2.8.0 move with the releases, and flask_migrate plus alembic mean database schema migrations are part of the upgrade path. Budget for a staging environment that mirrors production OpenSearch, because a search backend version mismatch is the kind of thing you want to find before the migration runs against the real index.

## Conclusion

Timesketch fits incident response teams that need several analysts working on the same timeline with shared tags, comments and stars, and it fits analysts who want an API or CLI instead of clicking through a UI. It does not fit a single examiner who wants a desktop artifact parser with no server to run: Plaso parses the data, but Timesketch is what makes the parsed events collaborative and queryable, and it needs OpenSearch, Redis, a database and a web stack. Before adopting it, read the install guide at timesketch.org, confirm the OpenSearch version your deployment targets, and check the config/ and docker/ directories in the repository against your environment.

## FAQ

### What is Timesketch used for?

It is used for collaborative forensic timeline analysis. Analysts place timelines into sketches, then add annotations, comments, tags and stars so a team can review the same events together.

### How do I install Timesketch?

The README points to the install guide at https://timesketch.org/guides/admin/install/ rather than listing steps inline. The repository provides a docker/ directory for containerized deployment, and setup.py requires Python 3.6 or higher.

### How do I use Timesketch?

The README links to the upload-data guide for adding timelines and to the users guide on basic concepts for the workflow. There is also a notebook container guide at https://timesketch.org/guides/user/notebook/ for analysis next to the sketch data.

### What is Timesketch?

Timesketch is an open-source web tool for collaborative forensic timeline analysis, licensed Apache-2.0. The README states that it is not an official Google product, only code owned by Google.

### What is a Timesketch alternative?

Plaso is the closest point of comparison, but it solves a different problem: it parses evidence and produces a timeline, while Timesketch stores that timeline and adds shared querying and annotation. A general OpenSearch or Elasticsearch deployment is the other option, and it would require building the sketch, tag and permission model yourself.

## Sources

- [google/timesketch on GitHub](https://github.com/google/timesketch)
- [Issues](https://github.com/google/timesketch/issues)
- [License: Apache-2.0](https://github.com/google/timesketch/blob/master/LICENSE)
- [README](https://github.com/google/timesketch/blob/master/README.md)
- [Releases](https://github.com/google/timesketch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-timesketch