A single compromised host can hold millions of timestamps across the file system, registry, event logs and browser data, and responders who cannot merge them into one ordered view miss the sequence that explains the intrusion. Plaso, the Python engine behind the log2timeline tool, extracts those events into a storage file that can then be filtered, tagged and exported. This guide explains the Plaso toolset (log2timeline, psort, pinfo, psteal and image_export), how to choose between full super timelines and targeted collection, how to filter and tag output so analysts find signal quickly, and how to run it defensibly. It goes deeper than the Open Source DFIR Tools Landscape Guide and is written for DFIR analysts and incident responders. Options and parser names were checked against the project repository and documentation (release 20261025) on 27 October 2026.
This is an independent guide from NHI Mgmt Group, based on the Plaso project's public documentation as of November 2026. It is not sponsored or reviewed by the Plaso project. Product features change, so confirm settings against the Plaso project's current documentation.
Key takeaways
- Plaso is a pipeline, not one command. log2timeline extracts events into a
.plasostorage file; psort filters, analyses and outputs it; pinfo describes it; psteal runs both with defaults. - Targeted beats exhaustive under time pressure. Forensic Artifacts definitions (
--artifact-filters) or YAML filter files (--file-filter) cut processing from hours to minutes for triage. - Tagging turns a timeline into findings. The bundled
tag_windows.txtlabels events such as new services (7045), failed logons (4625) and cleared logs (104, 1102), so analysts start from known-bad patterns. - Everything is UTC by default. psort writes UTC unless
--output-time-zoneis set; agree the case time zone before analysts compare notes. - Some analysis plugins send data out. The virustotal and chrome_extension plugins contact external services; disable them for sensitive cases or isolated workstations.
What the tool does
Plaso (Plaso Langar Að Safna Öllu, "super timeline all the things") is an open source engine, licensed Apache-2.0, that collects timestamped events from individual files, directories, mount points or storage media images and aggregates them for timeline analysis. It replaced the original Perl log2timeline. Releases are date-versioned (for example 20261025) and the project recommends using a packaged release no older than six months rather than the development branch.
The command-line tools
| Tool | Purpose | Typical use |
|---|---|---|
log2timeline | Extracts events from a source into a Plaso storage file, with metadata about the collection | log2timeline.py --storage-file case.plaso image.E01 |
psort | Post-processes storage files: filter, sort, deduplicate, run analysis plugins and write output | psort.py -o dynamic -w case.csv case.plaso |
pinfo | Reports what a storage file contains: sources, parsers used, event counts, warnings | Validate a run before analysis; --sections sources |
psteal | Runs log2timeline and psort in one go with a limited subset of options | Quick look at a small image: psteal.py --source image.raw -o dynamic -w out.csv |
image_export | Exports file content from an image by extension, path filter, signature or date range | Pull executables or registry hives for other tools |
Sources and parsers
log2timeline scans the source first. If it finds several partitions, an encrypted volume (BitLocker credentials such as a recovery password can be supplied) or Volume Shadow Copies, it prompts; --partitions, --vss_stores and --unattended make runs non-interactive. Parsers are grouped into presets (for example win7, winxp, linux, macos, webhist) selectable with --parsers, and --info lists everything available in your build. Parsers relevant to most intrusion cases include:
| Platform | Parsers (as named in Plaso) | Evidence |
|---|---|---|
| Windows | winevtx, winreg, mft, usnjrnl, prefetch, lnk, winjob, recycle_bin, setupapi, esedb | Event logs, registry keys, file system metadata, execution and file-open traces |
| Linux | syslog, systemd_journal, utmp, selinux, bash_history, zsh_extended_history, Docker container and layer parsers | Logons, commands, services, container activity |
| macOS | unified_logging, fseventsd, plist plugins (login items, background items), macostcc | Persistence, file events, privacy permission grants |
| Cloud and network | aws_cloudtrail_log, azure_activity_log, gcp_log, apache_access, aws_elb_access, ivanti_vc0 | Control-plane actions and edge device logs alongside host evidence |
| Other tools | bodyfile, jsonl | Import output from other tools (for example a Volatility 3 timeliner bodyfile) |
Defender use cases
Full super timeline or targeted timeline?
| Approach | How | Choose it when | Trade-off |
|---|---|---|---|
| Full super timeline | Default parsers over the whole image | Scoping is unclear, the case may go to litigation, or you need to prove absence of activity | Hours of processing and millions of events; analysts drown without filters |
| Artifact-targeted | --artifact-filters with Forensic Artifacts definition names (or a file of names) | Fast triage of known high-value artefacts across many hosts | Misses evidence outside the chosen artefacts |
| Filter-file targeted | --file-filter with a YAML include/exclude file such as the bundled filter_windows.yaml | You want precise control of paths, for example MFT, UsnJrnl, hives, LNK, jump lists, event logs and prefetch | Filters apply at source level only, not inside archives; artifact and file filters cannot be combined |
| Single file or log set | Point log2timeline at a file or directory | Exported logs (EVTX, CloudTrail) collected by other means | No file system context |
A common pattern is to collect triage packages with a tool such as KAPE or Velociraptor, run targeted Plaso processing on each, and keep full images for the hosts that matter. See the KAPE and Triage Collection Guide and the Velociraptor Guide.
Filtering and analysis with psort
- Time slices:
--slice "2026-03-04T10:15:00"returns events five minutes either side of a pivot time;--slice_sizewidens the window. Since 20200613 the value must be ISO 8601. - Event filters: expressions such as
parser is 'winevtx' and event_identifier is 4624, with operators includingcontains(case-insensitive substring),regexp,iregexp, comparison operators andnot.--sliceradds context events around each match. - Date filters: restrict output to the incident window to reduce volume; set
--output-time-zoneonly when every reader understands the offset. - Duplicates: psort removes duplicate events by default;
-akeeps them, which matters when duplicates come from different Volume Shadow Copies. - Tagging:
--analysis tagging --tagging-file tag_windows.txtapplies labels such asapplication_execution,login_failed,service_new,task_schedule,autorun,file_download,firewall_changeandeventlog_cleared; Linux and macOS rule files ship too. Then filter ontag contains 'service_new'. - Hash lookups: log2timeline hashes files by default; the
bloomandnsrlsvrplugins label known files, which helps exclude operating system noise.
Questions a tagged timeline answers
| Question | Plaso evidence | Related ATT&CK technique |
|---|---|---|
| When did the attacker install persistence? | service_new (System 7045), task_schedule, autorun tags, registry key last-written times | T1543.003 Windows Service, T1053.005 Scheduled Task, T1547.001 Registry Run Keys |
| Which account logged on, and from where? | Security 4624 and 4625 records, RDP and SMB events, Linux login tags | T1021.002 SMB/Windows Admin Shares |
| What ran first on patient zero? | Prefetch, Amcache, LNK and jump lists ordered against browser downloads | T1204.002 Malicious File |
| Were logs tampered with? | eventlog_cleared tag (104, 1102), gaps in event record sequences | T1685.005 Clear Windows Event Logs, T1070 Indicator Removal |
| Were files timestomped? | Differences between $MFT attribute times and $UsnJrnl records | T1070 Indicator Removal |
For the analytical method (pivots, gaps, clock skew and reporting), see the Forensic Timeline Analysis Guide and the Windows Forensic Artefacts Guide.
Output choices
psort no longer writes to stdout (since 1.5.0); use -w. Output modules include dynamic (default, configurable with --fields and --additional_fields), l2tcsv (legacy 17-field CSV), json, json_line, tln, l2ttln, xlsx, and, with optional dependencies, opensearch and opensearch_ts for Timesketch. Runtime fields such as sha256_hash, file_entropy and yara_match help pivot to malware analysis. Timesketch, Google's open source collaborative timeline tool, is the usual front end when several analysts share a case.
Deployment and safe use
- Install a packaged release: the project recommends the Docker image (
log2timeline/plaso) or distribution packages. For isolated forensic networks,docker savethe image, move it on verified media anddocker loadit. - Mount evidence read-only: pass evidence into the container with a read-only bind mount and write the storage file to a separate case volume.
- Hash first: hash images before processing and record the Plaso version, command line and parser preset in case notes.
--logfilecaptures the run log, and pinfo output belongs in the case file. - Size the host: each worker can use more than a gigabyte of memory on large images; set
--workersand--worker_memory_limitto match the analysis host, and use--temporary_directoryon fast local storage. - Control outbound calls: do not run the
virustotalorchrome_extensionanalysis plugins on sensitive cases unless policy allows sending hashes or extension IDs to external services. - Protect output: timelines contain usernames, file paths, URLs, email subjects and sometimes command lines with secrets; store and share them like the image. See the Evidence Handling and Chain of Custody Guide.
- Test before you need it: process a known-good image of your standard build each quarter, compare event counts with the previous release and note parser warnings.
Detection and hardening value
Timelines show what your telemetry missed. After each case, compare the Plaso sequence with what the SIEM and EDR alerted on and close the gaps.
| Timeline finding | Improvement | Framework reference |
|---|---|---|
| Service installed (7045) with no alert | Detection on new services with unusual paths; see the Sigma Rules Guide | NIST SP 800-53 SI-4 |
| Security log cleared (1102) | Forward logs off-host so clearing does not destroy them; alert on 1102 and 104 | NIST SP 800-53 AU-9; see the Windows Event Forwarding Guide |
| Activity before log retention starts | Extend retention for high-value logs | NIST SP 800-53 AU-11 |
| Execution visible only in prefetch or Amcache | Enable process creation logging (4688 with command line, or Sysmon); see the Sysmon Guide | NIST CSF 2.0 DE.AE-03 |
| Root cause reconstructed | Feed into lessons learned and control changes | NIST CSF 2.0 RS.AN-03 |
Where identity fits
Timelines are often the only record of when a service account or local administrator was first used from an unexpected host. Filter on logon events for each privileged and non-human account in scope and compare against its expected source systems. See the Service Account Security Guide.
Measuring the capability
- Time to first timeline: hours from evidence receipt to a tagged, filtered timeline for a triage package (target under two hours).
- Parser warning rate: warnings per run from pinfo, tracked across releases to catch silent parsing failures.
- Telemetry gap count: events of attacker activity found only in the timeline, not in SIEM or EDR, per case.
- Release currency: age of the deployed Plaso release against the six-month recommendation.
Common failure patterns
- Full timelines for every host: processing every image exhaustively stalls the investigation; triage with filters and go deep where the evidence points.
- Time zone confusion: analysts mix UTC output with local-time notes from logs or interviews and misorder events; state UTC in every report.
- Interactive prompts in automation: pipelines hang on a partition or VSS prompt; use
--partitions,--vss_storesand--unattended. - Dropping duplicates blindly: deduplication hides the fact that an artefact existed in an older shadow copy; keep
-aoutput for VSS work. - Ignoring pinfo: a run that silently skipped an encrypted volume or failed a parser looks like an empty period of activity.
Alternatives
| Option | Choose it when | Trade-off |
|---|---|---|
| Plaso plus Timesketch | Multi-artefact timelines shared by several analysts | Runs with an OpenSearch back end |
| Single-artefact parsers (for example Eric Zimmerman's MFTECmd and related tools) | Fast, precise parsing of one artefact type with CSV output | You merge and normalise timelines yourself |
| Hayabusa or Chainsaw | Fast Sigma-based triage of Windows event logs only | Focused on Windows event logs; see the Hayabusa and Chainsaw Guide |
| The Sleuth Kit mactime and bodyfiles | File system timelines only | Focused on file system metadata |
| Commercial forensic suites | Teams needing GUI workflows, vendor support and court-tested reporting | Licence cost; confirm capabilities with the vendor |
Small teams can run psteal or targeted log2timeline in Docker on a workstation; larger teams typically automate processing of triage packages straight into Timesketch so analysts start from a tagged timeline.
Practitioner checklist
- Deploy a pinned Plaso release (Docker or package) on the forensic workstation and record its version per case.
- Maintain a tested filter file and an artifact list for your standard Windows and Linux builds.
- Run log2timeline with
--unattendedand explicit partition and VSS choices in automated pipelines. - Check every storage file with pinfo before analysis and file the output with the case.
- Run the tagging analysis plugin and start review from tagged events.
- Agree and state the time zone (UTC by default) in all timeline output and reports.
- Disable outbound analysis plugins for sensitive cases.
- Compare each case timeline against SIEM and EDR alerts and raise detection gaps.
Standards and references
- log2timeline project: Plaso repository
- Plaso documentation: Using psort
- Plaso documentation: User's Guide
- ForensicArtifacts: Digital Forensics Artifact Repository
- Timesketch: Collaborative forensic timeline analysis
- NIST: SP 800-86 Guide to Integrating Forensic Techniques into Incident Response
- MITRE ATT&CK: Indicator Removal
- NIST: Cybersecurity Framework 2.0
Related NHI Mgmt Group resources: Open Source DFIR Tools Landscape Guide · Forensic Timeline Analysis Guide · Digital Forensics (DFIR) Guide · Volatility 3 Guide · Hayabusa and Chainsaw Guide