Sandboxing

Sandboxing

The injector can start ffxiv_dx11.exe inside a Windows AppContainer. AppContainers are Windows' solution to application sandboxing. This means that the game and plugins won't be able to access and read files that aren't explicitly granted.

At the moment, this is only intended for power users, and there is no UI or broker process that can grant additional permissions at runtime and there are no plans to expand that right now. Some of the semantics around how this works and is set up don't really make it feasible to expose to users at the moment, see "known issues".

Setup

To start using sandbox mode, you have to run the following command one-time from an elevated/admin cmd/powershell:

Dalamud.Injector.exe sandbox-prepare

This creates the AppContainer profile, works out which paths the sandbox needs and adds the ACLs. Admin is needed because your game install or any other directories that should be granted may be owned by BUILTIN\Administrators, which prevents us from changing DACLs.

Then to launch the game normally inside the sandbox:

Dalamud.Injector.exe launch --sandbox
Dalamud.Injector.exe launch --sandbox-config=D:\my\dalamudSandbox.json

sandbox-prepare also takes -g / --game= and --sandbox-config=, the same way as launch. You need to use the same arguments to make sure permissions are granted to the appropriate directories. -g is only necessary if the game path you're trying to use differs from what is set up in XL.

The ACLs persist, so sandbox-prepare only needs to be run if you change the sandbox config. Launching with a sandbox configuration should print warnings when changes need to be applied.

Configuration

The sandbox config is at %AppData%\XIVLauncher\dalamudSandbox.json or wherever --sandbox-config= points. All fields are optional.

If you want to create a default configuration, pass --write-config to the sandbox-prepare command.

{
  "enabled": true,
  "containerName": "dalamud.game",
  "capabilities": ["internetClient", "privateNetworkClientServer"],
  "loopbackExempt": false,
  "allowedPaths": [
    { "path": "D:\\mods", "write": true },
    { "path": "%USERPROFILE%\\Desktop\\ffxiv", "write": false }
  ]
}

• enabled: Whether sandboxing is enabled. If you place the config at %AppData%\XIVLauncher\dalamudSandbox.json and have this set to true, sandboxing will apply by default and can be overridden by --no-sandbox.
• containerName: The AppContainer/profile name. You generally don't have to change this because we don't store anything inside the container storage at the moment. (though %LocalAppData% is redirected to a private folder managed by Windows, so if a plugin writes there, that would be specific to the container)
• capabilities: internetClient, internetClientServer and privateNetworkClientServer map to the fixed well-known RIDs. Anything else is run through DeriveCapabilitySidsFromName. You need internetClient to connect to servers.
• loopbackExempt: AppContainers can't talk to 127.0.0.1 at all or open localhost sockets and there is no capability for it, we need to add a special firewall rule to enable it. A bunch of plugins need this. If you change this, you need to run with sandbox-prepare again, because adding the rule needs admin.
• allowedPaths: Additional paths the game can read to or write from. You can set write: true to allow modifications and environment %VARS% are expanded. You can use this to add additional directories, outside of the ones that are already added.

Default grants

Access	Paths
read + execute	game directory, Dalamud working dir, runtime dir, dalamudAssets\dev
modify	installedPlugins, dalamudUserData (config + logs + temp), Documents\My Games\FINAL FANTASY XIV - A Realm Reborn
nothing	everything else

Take care not to grant modify permissions to any paths that can change the runtime behavior of the injector or the sandbox in a manner that could compromise code running outside of the sandbox, for example, by granting modify to the runtime or dalamud binary directory. The injector has some basic checks to prevent this.

Dalamud user data

The sandbox mode copies Dalamud's config and db out of the XIVLauncher root into %AppData%\XIVLauncher\dalamudUserData\ the first time you run in sandbox mode. Logs, crash dumps and temp files will also be written there (since the normal temp folder isn't accessible in app containers).

This is necessary because we can't grant any permissions to %AppData%\XIVLauncher without compromising the sandbox.

Known issues (fixable?)

• The crash handler is spawned from inside the game, so it inherits the container. Dumps and the dialog work, but it can't restart the game or enable safe mode
• No "safeguards" or interlocks that make sure that running Dalamud unsandboxed by accident doesn't result in exposure to malware. Ideally we would not be loading plugins or something like that, and show a message, configurable somewhere.
• Controller support seems spotty
• Steam overlay doesn't seem to work

Known issues (unfixable)

• Plugins aren't isolated from each other and still have full access to data from other plugins and the game itself
• Registry/HKCU isn't accessible, so whatever needs it may need a fallback. Dalamud already fails gracefully (but we only use it for dark mode detection)
• Built-in file dialogs will show Desktop/Documents/etc. but can't open them unless granted (may be done through a broker process instead)
• Windows only. On Linux, you can use one of the existing sandboxing solutions like bubblewrap.