Timesketch Documentation

The frontend-v3 package uses the following modern web stack:

• Framework: Vue 3 and Vuetify 3
• State Management: Pinia
• Routing: Vue Router
• Layouts: vite-plugin-vue-layouts
• Build Tool: Vite (provides fast cold starts and HMR)
• Component Management: unplugin-vue-components for automated component importing

Timesketch uses OpenSearch index mappings to define how data from different sources is stored and indexed. This ensures that data from Plaso, CSV, or JSONL imports is searchable and correctly typed.

Timesketch uses two primary mapping files located in the data/ directory of the repository:

• plaso.mappings: Used for .plaso file imports.
• generic.mappings: Used for CSV and JSONL file imports.

To begin using Timesketch, follow these primary workflows:

• Installation: Follow the official Install Timesketch guide for administrative setup.
• Data Ingestion: Learn how to Upload data to create timelines.
• Core Usage: Refer to the Users guide to understand basic concepts and how to navigate the tool.
• Notebook Integration: If you need to add a Notebook container for advanced analysis, follow the Notebook Installation guide.

To run the legacy frontend development environment, you need two active shells:

1. Main Webserver: Start the API server using gunicorn in the first shell.
2. Development Webserver: Start the Vue.js development server in the second shell. This spawns a listener on port 5001.

Access the application at http://localhost:5001/login.

# 1. Start the main webserver (API, etc.)
$ CONTAINER_ID="$(docker container list -f name=timesketch-dev -q)"
$ docker exec -it $CONTAINER_ID gunicorn --reload -b 0.0.0.0:5000 --log-file - --timeout 600 -c /usr/local/src/timesketch/timesketch/gunicorn.conf.py timesketch.wsgi:application

# 2. Start the development webserver
$ CONTAINER_ID="$(docker container list -f name=timesketch-dev -q)"
$ docker compose exec timesketch yarn run --cwd=/usr/local/src/timesketch/timesketch/frontend serve

You can ingest timeline data into Timesketch using .csv or .jsonl files. While you can include any number of custom attributes, the following three fields are mandatory for the UI to render events correctly:

• message: A string containing an informative message about the event.
• datetime: The event timestamp in ISO8601 format (e.g., 2015-07-24T19:01:01+00:00).
• timestamp_desc: A string explaining the timestamp type (e.g., file created).

Requirements:

• File Extensions: Files must end in .csv or .jsonl or the import will fail.
• Missing Fields: If mandatory fields are missing, you must use the Headers Mapping functionality in the UI to map existing columns to these mandatory names.

If imports are failing, check the following:

• Ensure the Celery worker is running and check its logs.
• Check the WebUI status of the import.
• Attempt to upload the same file using import_client.py instead of the WebUI to isolate the issue.
• Test with a known sample file (e.g., sigma_events.csv).

CSV Import specific checks:

• Verify CSV headers meet minimum requirements.
• Check for encoding issues.
• Provide headers and a few lines of sample content (scrambled for PII) when reporting issues.

Plaso Import specific checks:

• Verify the Plaso version installed on the server using psort.py --version inside the Docker container.
• Identify the Plaso version used to create the file.
• Use pinfo.py $FILENAME inside the Docker container to check file compatibility.

Intelligence items in Timesketch are typically Indicators of Compromise (IOCs) like IP addresses or file hashes. You can add them in two ways:

1. Using automatic suggestions: Timesketch parses event attributes for potential IOCs. When a match is found (e.g., a SHA-256 hash or IP address), the string is displayed with a grey highlight. Click the highlighted string to open the add local intelligence dialog.
2. Manual selection: Select any string with your cursor. The string will become highlighted, allowing you to add it as intelligence.

You can optionally change the IOC type before confirming the suggestion.

Once the services are running, you can access the application via the following endpoints:

• Timesketch UI: http://127.0.0.1:5000/
  • User: dev
  • Password: dev
  • Note: Login sessions persist across container restarts because the secret key is stored in a .dev_secret_key file.
• Metrics (Prometheus): http://127.0.0.1:9090/

Use the lint command to check for linting errors and automatically fix fixable issues in the codebase.

yarn run lint