Stable Signing: TCC Grants That Survive brew upgrade¶
Files: app-setup/templates/stable-sign.sh,
scripts/server/setup-auto-updates.sh (deploys it and hooks it into the daily
brew upgrade), app-setup/podman-transmission-setup.sh (puts the stable mirror
first in the supervisor's PATH), app-setup/templates/transmission-trigger-watcher.sh
(puts the stable bash first in the watcher's PATH), tests/stable-sign.bats,
tests/podman-machine-start.bats, tests/transmission-trigger-watcher.bats
Deployed: /usr/local/bin/<hostname>-stable-sign.sh, mirror tree under
/usr/local/stable/<formula>/, signing identity "<HOSTNAME> Local Code
Signing" in /Library/Keychains/System.keychain
The problem¶
After every reboot or container recreate, macOS showed the operator desktop a
dialog: "podman-remote" would like to access files on a network volume. The
podman-transmission-vm supervisor blocked on it. On 2026-09-03 a routine
container recreate at 08:51 stalled until someone clicked Allow at 09:26.
Adding podman-remote to Full Disk Access did not help.
Why the prompt exists¶
The Podman VM shares /Users/operator/.local/mnt/<share> (an NFS mount) into
the container over VirtioFS. The VirtioFS I/O is performed by Apple's
com.apple.Virtualization.VirtualMachine XPC service. When that service opens
a file on a network volume, macOS Tahoe checks the
kTCCServiceSystemPolicyNetworkVolumes privacy grant. XPC services are not
their own TCC client. macOS attributes the access to the responsible
process, and the rule observed on YOUR_SERVER is: the first non-Apple binary
below the LaunchAgent's /bin/bash. Everything under it inherits.
For the podman supervisor that chain is timeout (coreutils gtimeout)
-> podman-remote -> vfkit. Before the bounded-timeout change (2026-08-25)
the responsible binary was podman-remote, which is why the TCC database
holds one row per podman version. With only podman mirrored, the first
restart on 2026-09-03 prompted for gtimeout instead. LaunchAgents that run
Homebrew bash directly get a row for bash for the same reason. So every
Homebrew binary on the path from the LaunchAgent to the protected access
needs a stable copy.
The same rule applies to FileBot. The trigger watcher (/bin/bash) puts
Homebrew first in PATH and runs transmission-done, whose
#!/usr/bin/env bash therefore resolves to Homebrew bash. That bash is the
first non-Apple binary above FileBot's reads on the NFS mount. On 2026-09-16
the daily upgrade installed bash 5.3.20; the first torrent after it
(2026-09-17 00:56) opened a "bash would like to access files on a network
volume" prompt, and FileBot's preview blocked for 19 hours until someone
clicked Allow at 19:53. Plex and the Transmission container also failed to
read the NAS during that window and recovered on the same click, so a pending
prompt appears to hold up other network-volume checks (observed, not proven).
The TCC database had one row per bash version (5.3.12, 5.3.15, 5.3.20).
Why the grant keeps disappearing¶
A TCC row is keyed on two things:
| Column | Value for a Homebrew binary |
|---|---|
client |
Resolved path: .../Cellar/podman/6.1.1/bin/podman-remote |
csreq |
Requirement derived from the signature: cdhash H"..." |
Homebrew binaries are only ad-hoc linker-signed with the generic identifier
a.out, so the only requirement macOS can derive is the binary's cdhash.
Both the path and the cdhash change with every release. The daily brew
upgrade LaunchDaemon (04:30) therefore silently invalidates the grant, and the
next VM start or container recreate re-prompts.
Why Full Disk Access did not help¶
FDA (kTCCServiceSystemPolicyAllFiles) is a different service in a different
database. It does not cover network volumes on Tahoe. Also, the entry was
added by the /opt/homebrew/bin/podman-remote symlink path, and TCC resolves
symlinks: the stored client path still pointed at the versioned Cellar path.
What was verified before building this¶
All four rows below were measured on YOUR_SERVER on 2026-09-03, not inferred:
experiments with a tiny C program (nvtest) that opens a file on the NFS
mount from a LaunchAgent (rows 1 to 3, each cycled more than once), plus
re-signing the live podman-remote while its VM was running (row 4: one more
prompt appeared on the next access):
| Change | Prompts again? |
|---|---|
| Rebuild ad-hoc binary at the same path | yes (cdhash) |
| Self-signed identity + fixed identifier, same path | no |
| Same signature, copy to a different path | yes (path) |
| Re-sign the binary a running VM is responsible for | once, then no |
Mirror podman only; timeout still from the Cellar |
yes (gtimeout) |
Signing with a self-signed identity changes the stored requirement to
which does not depend on the binary's contents. Combined with a fixed path, the grant matches forever.
The fix¶
stable-sign.sh keeps a stable mirror of each configured formula:
- Drop the
.source-versionstamp, thenrsync -a --checksum --delete${HOMEBREW_PREFIX}/opt/<formula>/bin/andlibexec/into/usr/local/stable/<formula>/. Theopt/link is Homebrew's version-independent pointer, so this always tracks the current release.--checksummatters because signing on a copy preserves the mtime, so rsync's size+mtime quick-check could otherwise leave a tampered stable copy in place. The relativepodman -> podman-remotesymlink is preserved (barepodmanin the supervisor executes the signed file through it), and podman finds vfkit/gvproxy at../libexec/podmanrelative to itself. - Re-sign the binaries named in
STABLE_TARGETSwith the local identity and identifierlocal.<hostname>.stable.<bin>. The signing happens on a temp copy that is thenmv'd over the original, so a running process keeps its old inode. - Verify with
codesign -v -R=<requirement>and write.source-version(theopt/link target) so later runs are no-ops until Homebrew moves the link.
Consumers put /usr/local/stable/<formula>/bin ahead of /opt/homebrew/bin
in PATH. For Podman that is the export PATH= line of
podman-machine-start.sh, which lists the podman and coreutils mirrors. For
FileBot it is the export PATH= line of transmission-trigger-watcher.sh,
which lists /usr/local/stable/bash/bin, so every #!/usr/bin/env bash
child of the watcher runs the signed bash.
Both timeout and podman are executed through Homebrew's own symlinks
(timeout -> gtimeout, podman -> podman-remote), so the kernel runs the
signed file and TCC keys on its path.
Never signed: vfkit (carries the com.apple.security.virtualization
entitlement, which codesign -f without --entitlements would strip) and
gvproxy. They are mirrored unchanged.
The signing identity¶
Created headlessly on first run:
openssl req -x509 -newkey rsa:2048 -days 3650 ... -config cs.cnf # EKU codeSigning
openssl pkcs12 -export ... -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES \
-macalg sha1
sudo security import id.p12 -k /Library/Keychains/System.keychain \
-T /usr/bin/codesign
Notes learned the hard way:
- OpenSSL 3's default PKCS#12 encryption is unreadable by
security import("MAC verification failed"). The legacy algorithms above work. -T /usr/bin/codesignis what lets codesign use the key without a GUI prompt from a LaunchDaemon. Noadd-trusted-certor partition-list change is needed.security find-identity -vhides the identity as untrusted; codesign signs with it anyway, and TCC matches on the certificate hash, not on trust.- The certificate is valid for 10 years (until 2036). Nothing warns before expiry; rotating it changes the requirement and costs exactly one re-prompt per binary.
- The identity is a stable label, not a trust boundary. The
-T /usr/bin/codesignACL applies to any local user, so the operator account can sign a binary that satisfies the exact requirement (verified). What keeps a forged binary from inheriting the grant is that TCC also keys on the path, and/usr/local/stableis writable only by the administrator. That is no weaker than the Homebrew binaries it replaces, whose ad-hoc cdhash anyone can produce, but do not read the signature as authentication.
Operations¶
# State of every target; exit 1 if anything is stale. Also lists every
# other entry in bin/: symlinks with their target, and unsigned files.
/usr/local/bin/<hostname>-stable-sign.sh --check
# Did the daily upgrade job's stable-sign step fail?
grep -E 'stable-sign|ERROR' ~/.local/state/<hostname>-brew-upgrade.log | tail
# Refresh after a manual brew upgrade (the daily daemon does this itself)
/usr/local/bin/<hostname>-stable-sign.sh
# Confirm the grant is keyed on the stable path and identity
sudo sqlite3 /Users/operator/Library/Application\ Support/com.apple.TCC/TCC.db \
"select client, auth_value from access where service='kTCCServiceSystemPolicyNetworkVolumes'"
Expected once adopted: one final prompt for
/usr/local/stable/coreutils/bin/gtimeout and one for
/usr/local/stable/bash/bin/bash (the responsible binaries), then none,
across brew upgrades and reboots. Which binary the prompt names is the
quickest way to find the responsible process when a new one appears: the
row it leaves in the TCC database (query above) is the path to mirror.
Adding another binary¶
Append "<formula>:<bin>[,<bin>]" to STABLE_TARGETS in the template,
redeploy with scripts/setup-auto-updates.sh --force, and make the consumer
use /usr/local/stable/<formula>/bin/<bin>. Check the whole process chain
from the LaunchAgent down: the first non-Apple binary is the one that needs
the stable copy, not the one that opens the file. A script with
#!/usr/bin/env bash that runs with Homebrew first in PATH runs Homebrew
bash, which then becomes that binary; put /usr/local/stable/bash/bin first
instead, as the trigger watcher does.
Cleanup after adoption¶
Old TCC rows for the Cellar paths are harmless but can be removed in System
Settings > Privacy & Security > Files and Folders. The FDA entry for
podman-remote does nothing and can go too.
Test architecture¶
tests/stable-sign.bats renders the template with test placeholders and runs
it against a fake Homebrew tree. codesign, security and sudo are mocked;
the codesign mock stores the identifier and certificate inside the file so
they travel with the bytes through the temp-copy-and-mv, exactly like a real
signature. rsync and openssl are real. tests/podman-machine-start.bats
checks the supervisor's PATH order and that a podman placed in the stable
directory is the one the loop executes.