← Files UnityARCHIVED FILE

skills/using-unity/references/unity-cli/SECURITY.md

16.3 KB · Nov 20, 2026 · 18:10 UTC

↓ Download file

See the change to this file →

# Security notes — unity-cli skill

This skill documents the official first-party [`unity` CLI](https://public-cdn.cloud.unity3d.com/hub/prod/cli/). A few of its capabilities are powerful by design and are flagged by automated skill scanners. They are intentional, first-party functionality with the safeguards described below.

## Accepted risks

These capabilities are accepted by design. Each is documented in full in the sections below; this table is the explicit, human-readable acknowledgment.

| Risk | Capability | Why it is accepted |
|---|---|---|
| `SEC_POWER_CAP` | Local Editor control and C# evaluation | Runs entirely on the local machine, as the current user, against the user’s own Editor — no remote access and no privilege the user lacks at their own terminal. |
| `SEC_INSTALL_PIPE` | Install one-liners piped to a shell | HTTPS to Unity’s first-party CDN only; the installer verifies a SHA-256 pin against a same-origin manifest before executing anything. |
| `SEC_AGENT_CONFIG_WRITE` | Writing agent skill files into AI clients’ configuration directories, turning an installed skill off or back on, and installing Unity’s own agent plugin into Claude Code, Codex, Grok Build, Antigravity, GitHub Copilot, or Qwen Code | Runs only on an explicit user command, is the command’s documented purpose, and is fenced by an ownership ledger — a copy this CLI did not write is never overwritten without `--force`, and the enable/disable verbs cannot act on one at all — plus symlink refusals and a warning before project-local installs from the home directory. The plugin install names one hardcoded first-party source, is performed by the agent’s own CLI (`claude`, `codex`, `grok`, `agy`, `copilot`, or `qwen`) rather than by writing files, and reinstalls nothing. |

## Accepted, by-design capabilities

### Installing skills into AI clients

`unity skill install` and `unity skill refresh` write skill files — this skill, and the `unity-pipeline` skill a project's `com.unity.pipeline` package ships — into AI clients' configuration directories, along with the Unity skills pinned from the Unity-Technologies/skills repository, which automated scanners flag as an agent-persistence pattern. `unity setup <agent>` installs the same skills only when its plugin can't be installed and the user agrees at the prompt or passes `--yes`. The writes happen only when the user runs the command (nothing installs at load or in the background), the capability is the command's advertised purpose, and it is fenced: an install ledger records every write and a directory this CLI did not write is reported, never overwritten, without explicit `--force` consent; targets that resolve through a symlinked path component are refused; a package-shipped tree is read with file-count, per-file, and aggregate size bounds and never through symbolic links; and `--local` from the home directory warns first.

The repository skills are downloaded, so the download is fenced too. The source repository and its download address are compiled into the CLI: no flag, setting or environment variable redirects them, and the download uses the CLI's normal TLS checks. The CLI pins a commit and a SHA-256 for each skill's file tree, and checks every skill against its pin before writing anything, so a changed or substituted archive writes nothing. Archive entries that would escape the skill folder, links, oversized files or archives, and non-text files are refused. Offline, only the skills embedded in the CLI are installed.

### Syncing skills when an agent session starts

`unity skill sync` is the one skill write that runs without the user typing it: Unity's agent plugin runs `unity skill sync --hook` when a session starts, which scanners flag as an agent-persistence pattern. The user consents by installing the plugin, whose description says it keeps the Unity skills current, and it is fenced more tightly than `skill install`. It writes only what a non-interactive `unity skill install` would: the embedded skills and the skills pinned and checked as above, into the one client the agent is. It never prompts, and has no `--yes` or `--force`, so it never overwrites a copy the user edited, a directory this CLI did not write, or a skill a plugin ships, and it leaves a disabled skill disabled. It runs no other command and installs no plugin or MCP server. After a run that reached the pinned repository it downloads nothing until the CLI or its pin changes. Under `--hook` its output is one plain line of context naming the skills it changed, or nothing.

### Turning an installed skill off and back on

`unity skill disable <skill>` and `unity skill enable <skill>` change whether a skill an AI client has already installed still loads. Disabling renames that skill's `unity-cli.md` to `SKILL.md.disabled` inside its own directory and records the choice; enabling renames it back. Automated scanners flag this as skill suppression — a skill that can switch other skills off is a recognized malicious pattern, and reading it that way is correct as a default. Here it is the advertised purpose of a user-run command, and it is fenced:

- **It can only reach installs this CLI itself recorded.** The set of skills these verbs can name comes entirely from the install ledger, so a skill this CLI did not install has no row, cannot be named, and cannot be found or touched. There is no path by which it disables a skill some other tool or the user placed.
- **Nothing runs at load or in the background.** Both verbs act only when the user runs them, on a skill the user names; `--dry-run` reports without touching the filesystem.
- **Nothing is deleted and no content is read or rewritten.** The only filesystem operation is renaming one fixed filename within the directory the ledger already records, so the skill's own files stay where they are and enabling restores the previous state exactly.
- **The paths are bounded the same way installs are.** The only path formed is the recorded install directory joined with a constant filename, that directory has already passed the ledger's absolute-path validation, and a target reached through a symlinked directory component is refused rather than followed — the same guard `install` and `refresh` apply.

The capability exists because a skill costs context in every session of the client that discovered it, whether or not it is ever used, so a user who installed several needs a way to stop paying for the ones a given project does not need — without deleting files they would otherwise have to reinstall.

### Installing Unity’s agent plugin (Claude Code, Codex, Grok Build, Antigravity, GitHub Copilot, Qwen Code, VS Code, OpenCode)

`unity setup claude` installs a plugin into Claude Code, which automated scanners flag as an agent-persistence pattern. It is fenced as follows. It runs only when the user runs the command, and this skill tells an agent to run it only when the user asks for the plugin or agrees to install it, never on its own initiative. The only source it can name is Anthropic’s official Claude Code marketplace, `anthropics/claude-plugins-official`, which lists Unity’s plugin and is compiled into the CLI: no argument, file, or environment variable can point it anywhere else. Claude Code accepts that marketplace name only from a repository under `github.com/anthropics/` ([Claude Code plugin security](https://code.claude.com/docs/en/plugins/security#identify-anthropics-marketplaces-by-name)), so a look-alike marketplace can’t take its place. It writes no files itself; it runs Claude Code’s own `claude plugin marketplace add` and `claude plugin install`, the documented install path, with fixed arguments, so Claude Code applies its own install handling. `--dry-run` prints both commands without running them, and an existing install is reported and never reinstalled or changed. It registers no MCP server of its own. After the plugin is installed or found already installed, it installs the Unity skills into the agent’s user-global skills folder, the same quiet run as `unity skill install <client>` that downloads from Unity’s pinned public skills repository with the same verification and the same refusal to overwrite an edited skill. A skill an older plugin still provides is skipped, and a failed skills step is a warning, not a failure. Every `unity setup <agent>` command below does the same for its own client.

`unity setup codex` and `unity setup grok` install the same plugin into Codex and Grok Build under the same fence: they run only when the user runs them, and this skill tells an agent to run them only when the user asks for the plugin or agrees to install it. Their source is Unity’s own first-party marketplace, `Unity-Technologies/unity-agent-plugin`, compiled into the CLI, and nothing can point either command elsewhere. Each writes no files itself and runs only the agent's own documented install commands with fixed arguments: `codex plugin marketplace add` and `codex plugin add`, or `grok plugin install … --trust`. `--trust` is Grok Build's consent flag for a non-interactive install, and it is passed only because the user ran the command. `--dry-run` prints the commands without running them, and an existing, enabled install is reported and never reinstalled or changed. A Codex plugin the user disabled (`enabled = false` in Codex’s `config.toml`) is the one exception: `unity setup codex` treats it as not installed and runs the same two `codex` commands again, which re-enables it. That only happens when the user runs the command.

`unity setup antigravity` installs the same plugin into Antigravity under the same fence. It runs only `agy plugin install` with Unity’s first-party repository, `Unity-Technologies/unity-agent-plugin`, as a fixed URL compiled into the CLI that nothing can point elsewhere, writes no files itself, prints the command under `--dry-run`, and reports an existing install without changing it.

`unity setup copilot` installs the same plugin into GitHub Copilot under the same fence. It runs only when the user runs it, names only the compiled-in first-party repository, writes no files itself, and runs only the Copilot CLI's own documented commands with fixed arguments: `copilot plugin marketplace add` and `copilot plugin install`. `--dry-run` prints the commands without running them, and an install Copilot records as enabled is reported and never reinstalled or changed. A plugin the user disabled counts as not installed, so the same two commands run again and re-enable it, only when the user runs the command. When the marketplace is already registered, `copilot plugin marketplace add` exits with an error saying so, and the command treats that one message as done and goes on to the install step; any other failure stops it.

`unity setup qwen` installs the same plugin into Qwen Code under the same fence. It runs only when the user runs it, names only the compiled-in first-party repository, writes no files itself, and runs only Qwen Code's own documented commands with fixed arguments: `qwen extensions install Unity-Technologies/unity-agent-plugin:unity --consent`, then `qwen extensions enable unity`. `--consent` is Qwen Code's flag for a non-interactive install, and it is passed only because the user ran the command. `--dry-run` prints the commands without running them, and an install Qwen Code has enabled for the current directory is reported and never reinstalled or changed. A disabled one counts as not installed, so the same two commands run again: the install fails because the extension exists, the command treats only that message, and only when the existing extension is Unity's own, as done, and the enable step turns it back on for the user's home directory. If it is still disabled for the current directory (a folder outside home), one more fixed command, `qwen extensions enable unity --scope workspace`, turns it on for that folder alone. Any other failure stops it.

`unity setup vscode` and `unity setup opencode` have no plugin CLI to run. Each installs the Unity skills for its client, as above, and runs no other command. `setup vscode` only prints how to add Unity’s plugin from the compiled-in first-party repository in VS Code and edits no VS Code file. `setup opencode` writes exactly one file, `~/.config/opencode/plugins/unity.js`, whose body is compiled into the CLI and whose path nothing can change. It runs only when the user runs the command. The file is written through a temporary file and a rename, its first line records a SHA-256 of the body the CLI wrote, and a later run replaces only a copy that still matches that digest. A file the user edited, or wrote themselves, is left alone with a warning unless the user passes `--yes`. `--dry-run` writes nothing. When OpenCode starts a session, the plugin runs one fixed command, `unity skill sync opencode --hook --format json`, in the background, ignores any failure, and shows only what that command returns as a toast and a context message. It takes no input from the session, and the skills it updates come from the same pinned repository and verification as `unity skill install`.

### Local Editor control and C# evaluation

`unity command`, `unity command script eval`, and `unity shell --protocol ndjson` can drive a Unity Editor that is already open on the same machine and run C# through the project's `com.unity.pipeline` package. This executes **entirely on the local machine, in the current user's account, against the user's own Editor** — it is not remote access and grants no privilege the user does not already have at their own terminal. It is the CLI's core value for AI-assisted and automated Editor workflows.

Machine/agent mode (`unity shell --protocol ndjson`) runs the exact commands the caller sends. It validates framing (malformed or unknown requests return an error frame rather than crashing or ending the session), runs every command non-interactively, and returns structured JSON response frames (JSON-serialized, so control characters are escaped for the consuming parser). Callers must feed it **trusted input only** — commands they construct themselves — and never commands assembled from untrusted third-party content, exactly as they would guard any shell.

### Launching the project’s own build

`unity build run` launches a player the CLI itself recorded from a previous `unity build` on the same machine — or the output the user names with `--build-path` — without rebuilding. It downloads nothing and runs nothing it did not just build or was not explicitly pointed at: a desktop player is started as the current user, and a WebGL build is served from a loopback-only local HTTP server that the default browser opens. Automated scanners flag documented executable paths (`./Build/…`) as local code execution; here the executable is the user’s own build artifact, on the user’s own machine, and the command refuses (exit 6) when no build has been recorded, when the recorded build’s platform cannot run on the current OS, or when its output is gone.
### Install via the official CDN

The documented install downloads and runs an install script from Unity's official CDN, `public-cdn.cloud.unity3d.com`, **over HTTPS (TLS)**. This pipe-to-shell pattern is a deliberate, industry-standard install convenience for a first-party tool. Beyond TLS, the script verifies the downloaded binary against the SHA-256 published in the channel's release manifest and aborts on mismatch — or when no SHA-256 tool is available — so a corrupted, truncated, or substituted download fails instead of executing. The manifest is fetched from the same CDN origin as the binary, so this is an integrity check against a bad or altered *download*, not a defense against a compromise of the origin itself; trust in the install ultimately rests on TLS and on Unity's control of that CDN.

On Linux the script installs a self-contained binary under `~/.local/bin` and does not modify system package sources. Separately, Unity publishes `.deb` and `.rpm` packages (the `.rpm` is GPG-signed) to its official repositories, for users who prefer package-manager-managed updates. Installing either **does** change system state, and the two differ:

- **Debian/Ubuntu (`.deb`, `apt`)** — adds a Unity apt repository entry and installs Unity's signing key into the system keyring (`/usr/share/keyrings`), so `apt` can verify and deliver subsequent updates.
- **RHEL/Fedora (`.rpm`, `dnf`)** — adds a Unity yum repository entry with `gpgcheck` enabled, pointing `dnf` at the published key URL. It imports no key at install time.

SHA-256: 75bb9f17b7dd4b2a0ae061a6eb980e18743e4c1267d6589972dfb2c4141c3745