App Translocation Notes

This thread has been locked by a moderator; it no longer accepts new replies.

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" + "@" + ""

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:
    birthday card.myapp

Such an app might try to find the Templates directory by:

  1. Getting the path to the main bundle

  2. 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:

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

  2. Safari downloads the zip archive to the Downloads folder and then unpacks it (assuming your haven’t tweaked your preferences).

  3. In Finder, navigate to the Downloads folder and launch the app.

  4. When Gatekeeper presents its alert, approve the launch.

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

    Note how the path isn’t ~/Downloads but something random. That’s why the official name for this feature is Gatekeeper path randomisation.

  6. Quit the app.

  7. Use Finder to relaunch it.

  8. Repeat step 5:

    % ps xw | grep NetNewsWire
    … /private/var/folders/wk/bqx_nk71457_g9yry9c_2ww80000gp/T/AppTranslocation/C863FADC-A711-49DD-B4D0-6BE679EE225D/d/

    The path is still randomised.

  9. Quit the app again.

  10. Use the Finder to move it to the desktop.

  11. And relaunch it.

  12. And repeat step 5 again:

    % ps xw | grep NetNewsWire
    … /Users/quinn/Desktop/

    The act of moving the app has cleared the state that triggered app translocation.

App Translocation Notes