Collecting the BTM Store on macOS
How to collect the macOS Background Task Management store and sfltool dumpbtm output: Full Disk Access, root, and what Aftermath, UAC and Velociraptor take.
On this page
TL;DR. On a live Mac, take two things: the text of sudo sfltool dumpbtm, and a copy of the folder /private/var/db/com.apple.backgroundtaskmanagement. Reading the folder needs root and Full Disk Access for the process doing the copy. Add the files that give the store context: launch plists, launchd's overrides, each user's legacy backgrounditems.btm, and the account records that name the users. Common triage tools take only part of this. Then drop the archive on BTM Parser; the How to get your data guide on the home page has the same commands.
What to collect
| Item | Path | Why |
|---|---|---|
| BTM store | /private/var/db/com.apple.backgroundtaskmanagement/ (every file) | The records themselves |
| Dump | output of sudo sfltool dumpbtm | What the running system reported |
| Launch plists | /Library/LaunchAgents, /Library/LaunchDaemons, /Users/*/Library/LaunchAgents | Join each record to its plist; find plists BTM does not know |
| launchd overrides | /private/var/db/com.apple.xpc.launchd/ | disabled.plist, disabled.<uid>.plist, loginitems.<uid>.plist |
| Legacy login items | /Users/*/Library/Application Support/com.apple.backgroundtaskmanagementagent/backgrounditems.btm | Login items from macOS 10.13 to 12, if still present |
| Accounts | /private/var/db/dslocal/nodes/Default/users/*.plist | Map generated UIDs to user names |
| OS version | /System/Library/CoreServices/SystemVersion.plist | The release the store comes from |
Copy the whole BTM folder, not only the newest file. The daemon migrates the store between format versions, and anything else in the folder is evidence too. More on versions in where the BTM store lives.
The account plists hold password hashes as well as names. Handle that copy accordingly. BTM Parser reads only names, UIDs and generated UIDs from them. If you prefer not to collect them, dscl . -list /Users GeneratedUID prints the mapping as text for your notes.
Privileges
Two separate barriers apply on a live Mac:
- root, because the store belongs to root and
sfltool dumpbtmneeds administrator rights. Run withoutsudo, it is reported to ask for administrator authorization in a dialog. - Full Disk Access, because the folder is privacy-protected. A Terminal without it gets "Operation not permitted", even as root. Grant it to the exact program that copies: Terminal, the collection agent or the tool binary.
Granting Full Disk Access is itself a change on the Mac: note when you did it so nobody mistakes your grant for the intruder's.
Live collection by hand
mkdir -p ~/case && cd ~/case
sudo sfltool dumpbtm > btm_dump.txt
paths=(/private/var/db/com.apple.backgroundtaskmanagement
/private/var/db/com.apple.xpc.launchd
/private/var/db/dslocal/nodes/Default/users
/Library/LaunchAgents /Library/LaunchDaemons
/System/Library/CoreServices/SystemVersion.plist)
for u in /Users/*; do
for d in "$u/Library/LaunchAgents" \
"$u/Library/Application Support/com.apple.backgroundtaskmanagementagent"; do
[ -e "$d" ] && paths+=("$d")
done
done
sudo tar -czf btm_collection.tar.gz "${paths[@]}" btm_dump.txt
shasum -a 256 btm_collection.tar.gz btm_dump.txt > hashes.txt
The script works in zsh and bash. It adds per-user folders only when they exist, because zsh stops a command on a pattern that matches nothing. tar keeps the paths, which is what attributes a legacy file or a LaunchAgents folder to a user. BTM Parser opens the .tar.gz as it is; you do not need to extract it.
Triage tools
| Tool | What it takes for BTM | Gap |
|---|---|---|
| Aftermath (Jamf) | Its persistence module saves sfltool dumpbtm output as Persistence/btm.txt and copies each user's legacy backgrounditems.btm into Persistence/raw | Does not copy BackgroundItems-v*.btm. Its launchd overrides step reads /var/db/launchd.db/com.apple.launchd/, an older location, not /private/var/db/com.apple.xpc.launchd/ |
| UAC | startup_items takes the LaunchAgents and LaunchDaemons folders and loginitems.*.plist from /private/var/db/com.apple.xpc.launchd; user_accounts takes the dslocal user plists | No artifact for the BTM folder, and disabled*.plist is not in the loginitems pattern |
| Velociraptor | MacOS.Detection.Autoruns uploads launch plists and disabled.*.plist; Generic.Collectors.File takes any glob you give it | No built-in BTM artifact in the core set |
These notes reflect the tools' public source at the time of writing. Check your version.
Aftermath
sudo ./aftermath -o /Volumes/CASE
Run it as root from a process with Full Disk Access. btm.txt in the archive is the dump: load it on BTM Parser as text. Add a manual copy of the BTM folder if you need the store itself.
UAC
Add a small artifact file, for example artifacts/files/system/btm_store.yaml:
version: 1.0
artifacts:
-
description: Collect the Background Task Management store.
supported_os: [macos]
collector: file
path: /private/var/db/com.apple.backgroundtaskmanagement
ignore_date_range: true
Then run it alone or next to your usual profile:
sudo ./uac -a ./artifacts/files/system/btm_store.yaml /tmp
UAC needs Full Disk Access on the Mac too. Its .tar.gz output can be dropped on BTM Parser directly.
Velociraptor
Use Generic.Collectors.File with Root / and globs such as:
private/var/db/com.apple.backgroundtaskmanagement/*
private/var/db/com.apple.xpc.launchd/*
Users/*/Library/Application Support/com.apple.backgroundtaskmanagementagent/*
Users/*/Library/LaunchAgents/*
The Velociraptor client needs Full Disk Access on the endpoint. Download the collection as a ZIP and drop it on BTM Parser.
Dead-box acquisition
From a full image, mount the Data volume read-only on an analysis host. Privacy protections do not apply there. The store is at private/var/db/com.apple.backgroundtaskmanagement/ relative to the volume root, the users under Users/. sfltool dumpbtm reports on the Mac it runs on, so it is of no use here. Parse the file instead. Local APFS snapshots, if any, may hold older copies of the store.
Handling the copies
- Never run
sfltool resetbtmon a Mac under investigation. Apple documents it as resetting login and background item data. - Keep the paths. The user folder in a path is what attributes per-user files.
- Hash on collection, and work on copies.
- Write down your own actions: the Full Disk Access grant, the commands and their times. They leave traces in the log and in TCC.
What to do with the result is in investigating Mac persistence with BTM.
FAQ
Do I need Full Disk Access if I already use sudo?
Yes. The BTM folder is privacy-protected: root alone gets Operation not permitted. The process doing the copy needs Full Disk Access.
Is sfltool dumpbtm output enough?
It is a good record of what the system reported, and often all you will get from a quick triage. Keep the store file too when you can: it can hold properties the text does not show, and it can be read again later.
Do common triage tools collect the BTM store?
At the time of writing, Aftermath saves sfltool dumpbtm output and the legacy per-user files, UAC's default artifacts do not include the BTM folder, and Velociraptor has no built-in BTM artifact. Add the folder to your collection yourself.
Can I run sfltool dumpbtm on a disk image?
No. sfltool dumpbtm reports on the Mac it runs on and has no documented option to read another store. On an image, copy BackgroundItems-v*.btm from the mounted Data volume and parse the file.
Related articles
Collect the macOS Background Task Management store
Copy the BTM folder, the sfltool dumpbtm text and the files that give it context from a live Mac, then load them in BTM Parser.
- Time
- 15 min
- Tools
- Terminal with Full Disk Access, An administrator account, BTM Parser (browser)
- Result
- A tar.gz with the BTM store, the dump, launchd plists and overrides, legacy login items and account records, plus SHA-256 hashes.
Grant Full Disk Access
In System Settings, give Full Disk Access to the program that will do the copy, for example Terminal, and note the time: the grant is itself a change on the Mac.
Dump the store
Run sudo sfltool dumpbtm and save the output to a text file.
Copy the files
Archive the BTM folder, the launchd override folder, the account plists, the LaunchAgents and LaunchDaemons folders and each user's legacy backgrounditems.btm with sudo tar, keeping their paths.
Hash
Compute SHA-256 hashes of the archive and the dump and keep them with your notes.
Load
Drop the archive or the dump on BTM Parser, or open them with Choose files.
Frequently asked questions
Do I need Full Disk Access if I already use sudo?
Yes. The BTM folder is privacy-protected: root alone gets Operation not permitted. The process doing the copy needs Full Disk Access.
Is sfltool dumpbtm output enough?
It is a good record of what the system reported, and often all you will get from a quick triage. Keep the store file too when you can: it can hold properties the text does not show, and it can be read again later.
Do common triage tools collect the BTM store?
At the time of writing, Aftermath saves sfltool dumpbtm output and the legacy per-user files, UAC's default artifacts do not include the BTM folder, and Velociraptor has no built-in BTM artifact. Add the folder to your collection yourself.
Can I run sfltool dumpbtm on a disk image?
No. sfltool dumpbtm reports on the Mac it runs on and has no documented option to read another store. On an image, copy BackgroundItems-v*.btm from the mounted Data volume and parse the file.