Skip to content

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.

Published on 5 min read
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

ItemPathWhy
BTM store/private/var/db/com.apple.backgroundtaskmanagement/ (every file)The records themselves
Dumpoutput of sudo sfltool dumpbtmWhat the running system reported
Launch plists/Library/LaunchAgents, /Library/LaunchDaemons, /Users/*/Library/LaunchAgentsJoin 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.btmLogin items from macOS 10.13 to 12, if still present
Accounts/private/var/db/dslocal/nodes/Default/users/*.plistMap generated UIDs to user names
OS version/System/Library/CoreServices/SystemVersion.plistThe 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 dumpbtm needs administrator rights. Run without sudo, 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

ToolWhat it takes for BTMGap
Aftermath (Jamf)Its persistence module saves sfltool dumpbtm output as Persistence/btm.txt and copies each user's legacy backgrounditems.btm into Persistence/rawDoes 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/
UACstartup_items takes the LaunchAgents and LaunchDaemons folders and loginitems.*.plist from /private/var/db/com.apple.xpc.launchd; user_accounts takes the dslocal user plistsNo artifact for the BTM folder, and disabled*.plist is not in the loginitems pattern
VelociraptorMacOS.Detection.Autoruns uploads launch plists and disabled.*.plist; Generic.Collectors.File takes any glob you give itNo 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 resetbtm on 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.

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.
  1. 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.

  2. Dump the store

    Run sudo sfltool dumpbtm and save the output to a text file.

  3. 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.

  4. Hash

    Compute SHA-256 hashes of the archive and the dump and keep them with your notes.

  5. 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.