iTerm2 Automation Scripts

Overview

iTerm2 exposes a Python API that lets users automate the terminal — creating windows and tabs, sending input, reacting to output, and driving arbitrary logic. These automation scripts live under ~/Library/Application Support/iTerm2/Scripts/. Scripts placed in the AutoLaunch/ subdirectory run automatically every time iTerm2 starts, which makes them both a workflow artifact and a potential persistence and code-execution mechanism.

Forensically, automation scripts reveal how a user or attacker configured their environment to behave: scheduled or event-driven tasks, custom tooling, integrations with other systems, and — in adversarial cases — automation that could stage or exfiltrate data. Scripts that auto-launch execute Python each time iTerm2 opens, so a malicious script here is a user-scoped persistence foothold that does not require a LaunchAgent.

Forensic Significance

Evidence Type	Forensic Value
Script inventory	What automation the user configured for their terminal
AutoLaunch scripts	Code that runs on every iTerm2 launch — persistence / auto-execution
Creation & modification times	When automation was introduced or last changed
Script content	The actual logic: tasks, integrations, potential exfiltration or staging
File extensions	Distinguishes Python (`.py`), packaging, and virtualenv files

File Locations

Artifact	Path	Notes
Automation scripts	`~/Library/Application Support/iTerm2/Scripts/`	Recursively enumerated
Auto-launching scripts	`~/Library/Application Support/iTerm2/Scripts/AutoLaunch/`	Run on every iTerm2 start

iTerm2 supports two script styles:

Simple scripts — a single .py file placed directly under Scripts/ (or Scripts/AutoLaunch/).
Full-environment scripts — a subdirectory containing the script plus a bundled Python virtual environment (an iterm2env folder). These produce many files (interpreter, site-packages) under the script's directory.

macfor enumerates the Scripts/ tree recursively, so both styles are captured.

AutoLaunch is a persistence vector

Any script under Scripts/AutoLaunch/ executes automatically whenever iTerm2 launches, with the user's privileges. Treat unexpected AutoLaunch scripts the same way you would an unexpected LaunchAgent — read the code and check its creation/modification times against the incident timeline.

Parsed Record Schema

macfor emits one iterm2_script metadata record per file found under Scripts/.

Field	Type	Description
`type`	string	Always `iterm2_script`
`app`	string	Always `iterm2`
`user`	string	Local user account the script belongs to
`relative_path`	string	Path relative to the `Scripts/` directory (e.g. `AutoLaunch/watch.py`)
`extension`	string	File extension (e.g. `.py`)
`size_bytes`	int	File size in bytes
`created_time`	string	RFC 3339 creation/birth time (from filesystem)
`modified_time`	string	RFC 3339 modification time (from filesystem)
`source_file`	string	Absolute path to the script file

Script Content

Metadata is always collected. The full content of each script is collected as a separate text artifact only when script-content collection is enabled (opt-in). When enabled, each content artifact records the script's relative_path and a SHA-256 hash of its bytes for integrity, preserving the original size and modification time.

Analysis Notes

Read AutoLaunch first: The AutoLaunch/ subdirectory is the highest-priority location — its scripts run on every launch. Use relative_path to filter for AutoLaunch/… entries.
Timeline the scripts: created_time marks when automation was introduced; modified_time marks the last change. Compare against the incident window to spot recently-planted automation.
Content review: When content collection is enabled, review the Python for network calls, filesystem staging, credential access, and calls to the iTerm2 API that send input or capture output. The SHA-256 supports matching against known-good or known-bad samples.
Virtual environments: Full-environment scripts bring an iterm2env folder with many bundled files; the meaningful logic is the user's own .py, not the interpreter/site-packages. Focus on the script entry point.
Correlate execution: An AutoLaunch script's activity may also appear in command history, saved state, CoreAnalytics, or Unified Logs — cross-reference to confirm it actually ran.

Manual Inspection

# List all automation scripts with timestamps
find ~/Library/Application\ Support/iTerm2/Scripts -type f -name '*.py' -print

# Prioritise auto-launching scripts
ls -la ~/Library/Application\ Support/iTerm2/Scripts/AutoLaunch/

# Hash a script for comparison
shasum -a 256 ~/Library/Application\ Support/iTerm2/Scripts/AutoLaunch/*.py

Tool Support

Tool	Support
macfor	Recursive metadata for every script plus opt-in full content collection with SHA-256
find / ls	Enumerate scripts and timestamps manually
shasum	Hash scripts for known-sample comparison