Skip to content

LLM Features Configuration

Timesketch includes experimental features leveraging Large Language Models (LLMs) to enhance analysis capabilities. These features include event summarization and AI-generated queries (NL2Q - Natural Language to Query). This document outlines the steps required to configure these features for Timesketch administrators.

Prerequisites

To use LLM features, specific Python libraries must be installed in the Timesketch container. Depending on your provider, you will need:

  • Google GenAI: google-genai (Comes preinstalled since v20260209 - Supports both Vertex AI and Gemini API)
  • Sec-Gemini: sec_gemini

There are two ways to install these dependencies:

For production environments, you should build a custom Docker image. This ensures the libraries persist across container restarts and upgrades.

  1. Build the image using the EXTRA_PIP_PACKAGES argument:

    docker build \ --build-arg EXTRA_PIP_PACKAGES="sec_gemini" \ -t timesketch:ai-enabled .

  2. Update your deployment to use this new image. Edit your docker-compose.yml to reference image: timesketch:ai-enabled (or the tag you used) instead of the official release image.

Option 2: Ephemeral Installation

For quick testing without rebuilding images, you can install the libraries into a running container. Note: These changes will be lost if the container is removed or recreated (e.g., during docker compose down and up).

# For Google GenAI
sudo docker exec timesketch-web pip install sec_gemini
sudo docker exec timesketch-worker pip install sec_gemini

LLM Provider Configuration

To utilize the LLM features, the Timesketch administrator must configure an LLM provider in the timesketch.conf file. It's possible to configure a specific LLM provider and model per LLM powered feature, or to use a default provider. For most features we recommend using a fast model (such as gemini-2.0-flash) for optimal performance, especially for the event summarization feature.

Edit your timesketch.conf file to include the LLM_PROVIDER_CONFIGS dictionary. Below is a sample configuration with explanations for each parameter.

# LLM provider configs
LLM_PROVIDER_CONFIGS = {
    # Configure a LLM provider for a specific LLM enabled feature, or the
    # default provider will be used.
    # Supported LLM Providers:
    # - ollama:  Self-hosted, open-source.
    #   To use the Ollama provider you need to download and run an Ollama server.
    #   See instructions at: https://ollama.ai/
    # - google_genai: Google GenAI (supporting both Vertex AI and Gemini API).
    #   To use the Google GenAI provider you need to:
    #   1. Configure either 'api_key' (for Gemini API) or 'project_id' (for Vertex AI).
    #   2. For Vertex AI: Set the GOOGLE_APPLICATION_CREDENTIALS environment variable
    #      to the full path to your service account private key file.
    #   3. Verify your instance has the `google-genai` lib installed.
    #     * $ sudo docker exec timesketch-web pip list | grep google-genai
    #
    #   IMPORTANT: Private keys must be kept secret. If you expose your private key it is
    #   recommended to revoke it immediately from the Google Cloud Console.
    'nl2q': {
        'google_genai': {
            'model': 'gemini-2.0-flash',
            'project_id': '', # Required if using Vertex AI
            'location': 'us-central1', # Optional for Vertex AI
        },
    },
    'llm_summarization': {
        'google_genai': {
            'model': 'gemini-2.0-flash', # Recommended model
            'api_key': '', # Required if using Gemini API
        },
    },
    'default': {
        'ollama': {
             'server_url': 'http://localhost:11434',
             'model': 'gemma2-2b-it',
        },
    }
}

Note: While users can enable/disable these features, the underlying LLM provider and its configuration are managed by the Timesketch administrator. Enabling these features may incur costs depending on the chosen LLM provider. Please review the pricing details of your selected provider before enabling these features.

Prompt and Data Configuration

Administrators can further customize the behavior of the LLM features by configuring the paths to various prompt and data files within the timesketch.conf file.

# LLM nl2q configuration
DATA_TYPES_PATH = '/etc/timesketch/nl2q/data_types.csv'
PROMPT_NL2Q = '/etc/timesketch/nl2q/prompt_nl2q'
EXAMPLES_NL2Q = '/etc/timesketch/nl2q/examples_nl2q'

# LLM event summarization configuration
PROMPT_LLM_SUMMARIZATION = '/etc/timesketch/llm_summarize/prompt.txt'
  • DATA_TYPES_PATH: Specifies the path to a CSV file defining common Timesketch data types for the NL2Q feature.
  • PROMPT_NL2Q: Specifies the path to the prompt file used by the NL2Q feature to translate a natural language into a Timesketch search query.
  • EXAMPLES_NL2Q: Specifies the path to the examples file used by the NL2Q feature. This file provides the LLM with examples of natural language queries and their corresponding Timesketch search queries, which help improve the accuracy of the NL2Q feature.
  • PROMPT_LLM_SUMMARIZATION: Specifies the path to the prompt file used by the event summarization feature. Administrators can modify this file to customize the summarization output to their specific needs. This template allows for injecting the event data into the prompt using Python-style string formatting using curly braces {}. Timesketch provides some default configuration files for both features:
  • NL2Q default configuration.
  • LLM Summarization default configuration.

AI Investigation Agent

Timesketch can also leverage a dedicated AI agent for in-depth log analysis within the Investigation View. If configured, this provides automated generation of investigative questions and findings.

For configuration details, see the Investigation View Setup Guide.