How to use the Timesketch Incident Timeline Builder agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions, reference files and optional scripts that an AI agent loads when a task matches the skill's description. This skill, building-incident-timeline-with-timesketch, is about reconstructing the order of events during an intrusion using Timesketch, an open-source collaborative forensic timeline tool.

Once active, the agent can guide you through setting up a Timesketch server, importing data from Plaso output, CSV or JSONL files, running analyzers, searching for suspicious activity such as lateral movement or PowerShell execution, and writing up the attack narrative as a story.

• Ingest Plaso (.plaso) files, CSV or JSONL timelines into a sketch
• Run built-in analyzers such as Sigma Analyzer and Chain of Events Analyzer
• Search for indicators like Windows event 4104 (PowerShell) or logon type 3 (network logon)
• Structure findings into an investigation story and a case report template

Install the skill from the ZIP

Download the ZIP file for this skill from this page and unzip it. The folder must contain SKILL.md at its top level, along with the assets, references and scripts folders.

For Claude Code, place the unzipped folder in ~/.claude/skills/ to make it available in all projects, or in a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/building-incident-timeline-with-timesketch/
• Project install: .claude/skills/building-incident-timeline-with-timesketch/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Prepare your environment before you start

The skill assumes you have a test or lab environment. It recommends testing before touching production evidence, and it assumes familiarity with incident response concepts and log formats. It does not teach those basics.

The skill's documented requirements are Python 3.8+ with the requests library (used by scripts/agent.py), a Timesketch server (Docker deployment recommended, with at least 8 GB RAM and Docker Compose), a Timesketch username and password for API login, Plaso (log2timeline) for parsing disk images and event logs, and the timesketch_importer command-line tool.

• Python 3.8 or newer with requests installed
• Timesketch server reachable over the network, ideally a lab instance
• At least 8 GB RAM and Docker Compose for the Docker deployment
• Timesketch username and password for the API
• Plaso (log2timeline) and timesketch_importer available on the command line

Trigger the skill with natural requests

You do not need special syntax. Describe the incident task in plain language and mention timelines or Timesketch. The agent should match the request to this skill from its description, which covers reconstructing event sequences and joint analyst tagging.

Good requests name the goal, the data you have and the authorization context. For example, say you have a Plaso file from a workstation and want a sketch built, or that three analysts need to annotate the same timeline.

• "Help me build a Timesketch timeline from this Plaso file for case 2025-001."
• "Import these CSV events into a Timesketch sketch and run the analyzers."
• "Search the sketch for PowerShell execution and lateral movement indicators."
• "Draft an attack narrative story from the tagged events for the incident report."

Work through the ingestion and analysis steps

The skill documents four ingestion methods: Plaso integration for comprehensive parsing, CSV import for quick triage, JSONL import for structured data, and Sigma rule integration. For a Plaso file, the agent will typically use timesketch_importer with a sketch name and timeline name. The skill also covers creating a sketch, adding timelines, running analyzers, and filtering with the Timesketch query language.

The skill's search examples include finding events by user, PowerShell execution (event_identifier:4104), and network logons (event_identifier:4624 with LogonType 3). Always check results against the original evidence before drawing conclusions.

Use the helper scripts carefully

The skill includes scripts/agent.py and scripts/process.py. The skill's own description says the Python helper scripts can call the Timesketch API to log in, list or create sketches, and run timeline import and analysis steps. The API reference shows the login endpoint (POST /login/) and sketch endpoints under /api/v1/sketches/.

Because these scripts send credentials and data to a live server, review them before running and point them only at a lab instance you are authorized to use.

• Read scripts/agent.py and scripts/process.py before running them
• Confirm the host URI and credentials point to the intended server
• Keep credentials out of shared notes and chat logs

Document the investigation

The skill includes assets/template.md, a forensic timeline investigation report template with sections for case information, evidence sources, investigation objectives, an attack timeline summary with ATT&CK technique columns, and key findings. The workflow guidance suggests building a story in Timesketch, annotating key events, and exporting it for the incident report.

• Fill in case information and evidence sources first
• Track objectives such as initial access, compromised accounts and persistence
• Record UTC times and ATT&CK technique IDs in the attack timeline table