AutoTimeliner

Automagically extract forensic timeline from volatile memory dumps.

AutoTimeliner runs multiple Volatility3 plugins against Windows, Linux, and macOS memory images, then merges their output into a single, sorted CSV timeline:

Generic Timeline Plugin

Plugin	What it captures
`timeliner`	Cross-plugin timestamp events (all OS families when supported)

Windows Plugin Set

Plugin	What it captures
`timeliner`	Timestamps from processes, registry, handles, etc.
`mftscan`	MFT file entries found in memory
`shellbags`	User folder-access history from registry hives

Linux Plugin Set

Plugin	What it captures
`linux.pslist`	Process start/exit timeline context
`linux.bash`	Shell command history evidence
`linux.lsof`	Open file evidence from processes

macOS Plugin Set

Plugin	What it captures
`mac.pslist`	Process start/exit timeline context
`mac.bash`	Shell command history evidence
`mac.lsof`	Open file evidence from processes

Windows Process & Execution Analysis

Plugin	What it captures
`psscan`	Active, terminated, and hidden processes with timestamps
`cmdline`	Command-line arguments for each process
`userassist`	Program execution evidence from Windows registry

Windows Network Analysis

Plugin	What it captures
`netscan`	Network connections with creation timestamps

Windows Malware Detection

Plugin	What it captures
`malfind`	Code injection and suspicious memory regions
`svcscan`	Windows services (useful for persistence detection)

Additional Windows Plugins (opt-in)

Plugin	What it captures
`dlllist`	DLLs loaded by each process
`filescan`	Files open in memory at acquisition time

Requirements

AutoTimeliner identifies the memory image family automatically and enables the appropriate plugin set for Windows, Linux, or macOS. For faster startup you can pass --os-hint to skip automatic detection.

Installation

With Poetry (recommended)

git clone https://github.com/andreafortuna/autotimeliner.git
cd autotimeliner
poetry install

With pip

pip install .

Usage

autotimeliner -f IMAGEFILE [-t TIMEFRAME] [-o OUTPUT] [options]

Options

Examples

Extract a full timeline from a single image:

autotimeliner -f TargetServer.raw

Filter to a specific time window:

autotimeliner -f TargetServer.raw -t 2023-10-17..2023-10-21

Process all .raw files in a directory, specifying output path:

autotimeliner -f './*.raw' -o /evidence/timeline.csv

Speed up startup when you already know the dump OS:

autotimeliner -f TargetServer.raw --os-hint windows

Use macOS alias values for convenience:

autotimeliner -f MacbookCapture.mem --os-hint darwin

Run only timeliner and shellbags (skip MFT scan):

autotimeliner -f TargetServer.raw --skip-mftscan

Full forensic scan (Windows plugin set + optional extended plugins):

autotimeliner -f TargetServer.raw --with-dlllist --with-filescan --with-handles --with-envars

Quick malware-focused scan:

autotimeliner -f TargetServer.raw --skip-timeliner --skip-mftscan --skip-shellbags

Linux-focused timeline collection (auto-enables linux plugins):

autotimeliner -f UbuntuWorkstation.mem

macOS-focused timeline collection (auto-enables macOS plugins):

autotimeliner -f MacbookCapture.mem

Output

The output CSV has the following columns:

Identification Performance

AutoTimeliner includes several optimizations to reduce identification time:

--os-hint bypasses automatic OS probing entirely.
Probe order is optimized using filename hints (for example linux, ubuntu, macos).
Identification results are cached per image key (path + size + mtime).

Cache file:

~/.cache/autotimeliner/volatility3/.autotimeliner_profile_cache.json

During detection, logs include probe progress and result messages such as:

OS probe attempt: family=windows plugin=windows.info.Info
OS probe returned no rows: windows.info.Info
Memory image identification succeeded: os=linux profile=linux:... probe=linux.banners.Banners

Migrating from v1 (Volatility2)

See docs/migration.md for a full comparison.

Key changes:

Volatility3 profile identification — AutoTimeliner performs a best-effort OS/profile probe via Volatility3 plugins.
Automatic symbol tables setup — Windows/macOS/Linux symbol packs are downloaded and installed automatically.
-p / --customprofile is deprecated — it is silently ignored.
mftparser → mftscan — same data, new plugin name.
No body files written to disk — data flows through Python directly to CSV.
mactime is now optional — use --use-mactime for the old body-file workflow.

Development

poetry install
poetry run pytest

License

MIT — see LICENSE.

Author

Andrea Fortuna — [email protected] — andreafortuna.org

Python	≥ 3.9
Volatility3	≥ 2.5	installed automatically via Poetry/pip
jsonschema	≥ 4.0	enables Volatility3 schema validation and avoids `Dependency for validation unavailable: jsonschema` warning
mactime	any	optional — only needed for `--use-mactime` legacy mode

`-f`, `--imagefile`	Memory dump file or glob (e.g. `'*.raw'`)
`-t`, `--timeframe`	Filter to `YYYY-MM-DD..YYYY-MM-DD` range
`-o`, `--output`	Output CSV path (default: `<imagefile>-timeline.csv`)
`--os-hint`	Force image OS family (`windows`, `linux`, `mac`; aliases: `win`, `macos`, `darwin`) and skip auto-identification
`--skip-timeliner`	Skip the timeliner plugin
`--skip-mftscan`	Skip the mftscan plugin
`--skip-shellbags`	Skip the shellbags plugin
`--skip-psscan`	Skip process scanning
`--skip-cmdline`	Skip command-line extraction
`--skip-netscan`	Skip network connection scanning
`--skip-userassist`	Skip program execution evidence
`--skip-svcscan`	Skip Windows services scanning
`--skip-malfind`	Skip malware/injection detection
`--with-dlllist`	Enable DLL analysis (slow)
`--with-filescan`	Enable open files scanning (many records)
`--with-handles`	Enable handle scanning (many records)
`--with-envars`	Enable environment variables extraction
`--use-mactime`	Legacy mode: use external `mactime` binary
`-v`, `--verbose`	Enable debug logging
`--version`	Print version and exit

`Timestamp (UTC)`	ISO 8601 UTC timestamp
`Source`	Plugin that produced the record
`Description`	File name, path, process, or registry key
`Detail`	Timestamp type, user, or extra context
`Inode`	MFT inode number (where applicable)
`UID` / `GID`	User/group identifiers
`Size`	File size in bytes
`Mode`	File mode string

autotimeliner

Most Popular