App translocation, officially known as Gatekeeper path randomisation, comes up from time-to-time. The best resource to explain it, WWDC 2016 Session 706 What’s New in Security, is no longer available from Apple so I thought I’d post some notes here (r. 105455698 ).
Questions or comments? Start a new thread here on DevForums, applying the Gatekeeper tag so that I see it.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
App Translocation Notes
Gatekeeper path randomisation, more commonly known as app translocation, is a security feature on macOS 10.12 and later. When you run a newly downloaded app, the system executes the app from a randomised path. This prevents someone from taking an app that loads code from an app-relative path and repackaging it to load malicious code.
IMPORTANT The best way to prevent your app from being tricked into loading malicious code is to enable library validation. You get this by default once you enable the hardened runtime. Do not disable library validation unless your app needs to load in-process plug-ins from other third-party developers. If you have an in-process plug-in model, consider migrating to ExtensionKit.
The exact circumstances where the system translocates an app is not documented and has changed over time. It’s best to structure your app so that it works regardless of whether it’s translocated or not.
App Translocation Compatibility
Most apps run just fine when translocated. However, you can run into problems if you load resources relative to your app bundle. For example, consider a structure like this:
MyApp.app
Templates/
letter.myapp
envelope.myapp
birthday card.myapp
Such an app might try to find the Templates directory by:
-
Getting the path to the main bundle
-
Navigating from that using a relative path
This won’t work if the app is translocated.
The best way to avoid such problems is to embed these resources inside your app (following the rules in Placing Content in a Bundle, of course). If you need to make them easily accessible to the user, add your own UI for that. For a great example of this, run Pages and choose File > New.
App Translocation Limits
There is no supported way to detect if your app is being run translocated. If you search the ’net you’ll find lots of snippets that do this, but they all rely on implementation details that could change.
There is no supported way to determine the original (untranslocated) path of your app. Again, you’ll find lots of unsupported techniques for this out there on the ’net. Use them at your peril!
If you find yourself using these unsupported techniques, it’s time to sit down and rethink your options. Your best option here is to make your app work properly when translocated, as illustrated by the example in the previous section.
App Translocation in Action
The following steps explain how to trigger app translocation on macOS 13.0. Keep in mind that the specifics of app translocation are not documented and have changed over time, so you might see different behaviour on older or new systems:
To see app translocation in action:
-
Use Safari to download an app that’s packaged as a zip archive. My go-to choice for such tests is NetNewsWire, but any app will work.
-
Safari downloads the zip archive to the Downloads folder and then unpacks it (assuming your haven’t tweaked your preferences).
-
In Finder, navigate to the Downloads folder and launch the app.
-
When Gatekeeper presents its alert, approve the launch.
-
In Terminal, look at the path the app was launched from:
% ps xw | grep NetNewsWire … /private/var/folders/wk/bqx_nk71457_g9yry9c_2ww80000gp/T/AppTranslocation/C863FADC-A711-49DD-B4D0-6BE679EE225D/d/NetNewsWire.app/Contents/MacOS/NetNewsWireNote how the path isn’t
~/Downloadsbut something random. That’s why the official name for this feature is Gatekeeper path randomisation. -
Quit the app.
-
Use Finder to relaunch it.
-
Repeat step 5:
% ps xw | grep NetNewsWire … /private/var/folders/wk/bqx_nk71457_g9yry9c_2ww80000gp/T/AppTranslocation/C863FADC-A711-49DD-B4D0-6BE679EE225D/d/NetNewsWire.app/Contents/MacOS/NetNewsWireThe path is still randomised.
-
Quit the app again.
-
Use the Finder to move it to the desktop.
-
And relaunch it.
-
And repeat step 5 again:
% ps xw | grep NetNewsWire … /Users/quinn/Desktop/NetNewsWire.app/Contents/MacOS/NetNewsWireThe act of moving the app has cleared the state that triggered app translocation.