Skip to content

Security: aimlapi/mercury-agent-aimlapi

Security

SECURITY.md

Security Policy

Mercury is a local-first agent that can run shell commands, edit files and talk to chat channels on your behalf. We take reports about its permission model seriously.

Supported versions

Version Supported
1.3.x (latest) Yes — security fixes land here
1.2.x and older No — please upgrade (mercury upgrade or npm i -g @cosmicstack/mercury-agent@latest)

Fixes ship as patch releases on the current minor line only.

Reporting a vulnerability

Please do not open a public issue for anything exploitable.

  1. Preferred: GitHub private vulnerability reporting — https://github.com/cosmicstack-labs/mercury-agent/security/advisories/new
  2. Fallback: email salman@cosmicstack.ai with "Mercury security" in the subject.

Include the version (mercury --version), the channel or surface involved, steps to reproduce (a deterministic harness or stub provider is ideal), and your assessment of impact. Tell us how you would like to be credited.

What to expect

  • Acknowledgement within 3 business days.
  • For High/Critical reports: a fix or a concrete mitigation plan within 14 days, and a patch release as soon as it is verified.
  • For Medium/Low reports: a fix in the next regular release, normally within 60 days.
  • We will keep you updated, credit you in the advisory and changelog unless you prefer otherwise, and coordinate publication timing with you.

Scope

In scope:

  • The agent runtime in this repository (src/): tool loop, permission manager, shell/filesystem/git tools, sub-agents and Mercury Bots.
  • Channels shipped here: CLI/TUI, local web dashboard, Telegram, Discord, Slack, Signal.
  • The web dashboard and its HTTP/SSE API.
  • Skills: install_skill, registry fetches and how installed skills are loaded.
  • Mercury Cloud client code that lives in this repository.

Out of scope:

  • Third-party model providers and their APIs (report to the provider).
  • The content and behaviour of skills you install yourself.
  • Attacks that require an already-compromised host account or the Mercury config directory (~/.mercury), or a dashboard deliberately exposed beyond 127.0.0.1 without a tunnel or proxy and authentication.
  • What a device you approved does while it is approved (revoke it with /server).
  • A model being persuaded to ask for something that you then approve.

Remote access

Mercury listens on 127.0.0.1 only; other devices reach it through a tunnel or VPN you set up (Tailscale Serve, Cloudflare Tunnel…). What protects it then (ADR-035 in DECISIONS.md):

  • Only this computer counts as local. A request is local only when it comes straight from this machine, with no proxy headers and a localhost Host. Everything through a tunnel is remote, even though the tunnel itself connects from 127.0.0.1.
  • New devices need your approval. Signing in from another device asks you (on your Telegram/WhatsApp/Discord/Slack/Signal chat, or /server and Mercury Desktop on this computer) before a token is issued. Unused devices expire after 30 days; revoking one closes its live connections.
  • A paired device is trusted like you, but can't make itself permanent. Actions that could outlive its access or hand out secrets — the terminal, Allow All, the workspace folder, Mercury's permissions, powerful bots, skills from a URL, plugins, channel tokens and admins, Cloud sign-in, a provider's server address, restart, the password — wait for your approval.
  • /server (or mercury server) turns remote access off, limits it to addresses you list, and manages devices; mercury doctor --security checks the setup.

A note on the permission model

Mercury's "Ask Me" mode is the real security boundary: risky commands and out-of-scope file access prompt you before they run. Shell commands take one of two lanes (ADR-016 in DECISIONS.md):

  • Argv lane (no prompt). A command is auto-approved only if it tokenises into a plain argument list with no shell syntax at all (no $, backticks, ~, redirection, pipes, ;/&&, unquoted globs, subshells); its program is on a short read-only allowlist (ls, cat, head, tail, wc, grep, rg, find, tree, du, df, ps, uname, pwd, which, echo, git status|diff|log|branch, and cd, handled in-process); its flags pass that program's policy (write/exec flags such as find -exec, rg --pre, git --output are refused); and every path argument stays inside the working directory or an approved scope. It then runs with execFile(absolute binary, argv) and a minimal environment, never a shell. Binaries are resolved once at startup from a fixed list of system directories (/usr/bin, /bin, /usr/sbin, /sbin, /usr/local/bin, /opt/homebrew/bin; System32 and Git on Windows), not from PATH. Git reads run with repository-configured hooks, pagers, external diffs and textconv filters disabled.
  • Approval lane (prompt). Everything else, including pipelines such as git log | head and && chains of read-only commands. You see the exact string; once approved it runs through the platform shell (sh -c / cmd.exe) with the daemon's environment. If an approved command can be expressed as argv it still runs without a shell. Allow All, an "always" answer, skill elevation and bot allow-lists approve through this lane without a prompt; hard-blocked commands are refused in every lane.

What this does and does not cover. The argv lane removes the shell from the auto-approved path, so the bypass class that kept recurring (redirection, expansion, chained commands, PATH substitution) no longer applies to it; what remains is the per-program flag policy, which is a deny/allow table we maintain and could still miss an option of an allowlisted tool. Path checks are lexical plus symlink canonicalisation for file tools; the argv lane checks path arguments lexically. Commands you approve run with whatever the shell does, by design.

Each agent has its own frozen permission context (channel, sender role, Allow All, allowed tools, session scopes). Delegated sub-agents get a context derived from their parent's when they are spawned and can never hold more than the parent: tool lists are intersected, scopes must be covered by the parent's, skill elevation is not inherited, and the allow-all of a scheduled/internal turn is neither inherited nor visible to sub-agents running at the same time.

Service files (mercury service install) write a fixed PATH rather than the installing shell's. Keep Ask Me on for any instance reachable by people you do not fully trust.

Known-fixed issues and the regression tests that cover them are listed in docs/security/.

There aren't any published security advisories