Jazz is an agent that executes real actions on your machine. It reads and writes files, runs shell commands, makes network requests, and drives external services. This document is both the vulnerability-reporting policy and the guide to running it safely.
Please do not open a public issue for security vulnerabilities.
Report privately via
GitHub Security Advisories. If you
cannot use that, email lvndry@proton.me with SECURITY in the subject.
Please include:
- What the issue is and why it matters
- Steps to reproduce, or a proof of concept
- The Jazz version (
jazz --version) and your platform - Any suggested fix, if you have one
You can expect an acknowledgement within a few days. We will keep you informed as we investigate, and credit you in the advisory unless you prefer otherwise.
Jazz is pre-1.0 and ships frequently. Fixes land on the latest published version: please
confirm the issue reproduces on the current release (jazz update) before reporting.
Some behavior that looks alarming is deliberate and documented rather than a vulnerability.
In scope: please report:
- A gated tool executing without approval, or any way to bypass the approval system
- Privilege escalation past the configured
--approval-policy/autoApprovetier - The command allowlist matching more than it should (e.g. a prefix-matching bypass)
- Credential or API-key leakage into logs, telemetry, transcripts, or error output
- Command or argument injection reachable from untrusted input
- Anything that lets a remote party act on a host running Jazz without local consent
Out of scope: working as documented:
--approval-policy high-risk(orautoApprove: true) permitting destructive commands. That tier exists to grant exactly that, and the docs say so.- A novel way to phrase a shell command that the denylist does not catch. The denylist is defense-in-depth against an accident, explicitly not a sandbox: approval is the real control.
- An agent acting on instructions embedded in content it fetched, when running at a tier that permits those actions. Prompt injection is real, which is why the tiers exist.
- Plaintext conversation transcripts under
~/.jazz/history/. Documented; treat that directory as sensitive. - An MCP server you configured doing something you did not expect. MCP servers are third-party code you chose to run.
- A trusted Jazz plugin doing something outside its manifest declarations. Plugins are executable in-process code, and those declarations are consent disclosures rather than a sandbox.
- An explicitly trusted command-risk plugin making a documented probabilistic judgment you disagree with, provided Jazz still enforces the hook's declared scope, validation, consent, and failure behavior. A bypass of those host controls is a security issue.
If you are unsure which side of that line something falls on, report it: we would rather triage a non-issue than miss a real one.
Approval gating is the primary control. 23 of the 54 built-in agent-facing tools are gated.
11 of them come in approval pairs: they do not act when the model calls them; they describe
what they would do (including a real diff for edits) and wait for approval, from you or from
the policy tier on an unattended run. The other 12 are plain tools above read-only, which the
executor holds until the same approval. Counts: tool inventory. Mechanism and risk tiers:
Tools & approval.
A shell command denylist blocks 56 patterns before execution: privilege escalation
(sudo, su), filesystem destruction (rm -rf /), remote code execution (curl … | sh),
power/runlevel changes (shutdown), and reads of /etc/passwd, /etc/shadow, /etc/sudoers.
Write confinement fences execute_command, write_file, edit_file, create_pdf, rm, mv, cp and mkdir to the working
directory, temp directories and tool caches with macOS Seatbelt or Linux bubblewrap. It is on by
default wherever nobody is attending (bridges, peers, goals, loops, headless jazz run) and covers
file writes only: reads and the network stay open. See write confinement.
Quoting the implementation directly, because it matters:
This is a defense-in-depth denylist, not a sandbox. It cannot stop a determined attacker , variable expansion, base64 obfuscation, eval, and other indirection paths can route around any string matcher.
Its job is catching an accident from a confused model. Do not treat it as a boundary against
a hostile one. If you need a boundary against reads or the network, use container isolation; write confinement bounds file writes.
Implementation and the documented set of known bypasses:
shell.ts,
shell.security.test.ts.
Environment sanitization. Shell commands run with every variable stripped whose name has a
secret word in it (SECRET, TOKEN, PASSWORD, CREDENTIALS, APIKEY, AUTH, PASS, COOKIE,
or KEY after another word), every variable Jazz reads a secret from (JAZZ_PEER_TOKEN_*,
JAZZ_WEBHOOK_*, JAZZ_NOTIFY_* target secrets), and everything prefixed SSH_. An agent's envAllowlist can exempt specific names when
a command genuinely needs one. Implementation:
env.ts.
Local-first data. Credentials resolve from the environment, OS keyring, or local config.
Telemetry is recorded locally by default and is exported only when you configure an OTLP endpoint.
JAZZ_OFFLINE=1 skips Jazz's update, public model-catalog, and library requests; it
does not block inference, tools, MCP, or telemetry export. See
Local and air-gapped models.
Audit trail. Tool activity is recorded under ~/.jazz/logs/, with per-run token and
cost records under ~/.jazz/telemetry/. Routine operational logs contain tool IDs,
outcomes, and durations rather than command text, arguments, results, or error messages.
The local tool audit record keeps a bounded, redacted argument shape. Credential-bearing
fields in structured metadata (including nested headers) are replaced with [redacted:<name>]
before a log is written. OTLP export is explicit and uses a private, bounded local outbox
for pending traces and logs. Local records can still contain sensitive non-secret context;
protect ~/.jazz and send OTLP only to an approved destination.
Jazz plugins run inside the Jazz process with the full authority of your OS user. Installing a plugin only verifies and stores its exact bytes; it does not trust, consent to, or enable them. Only a local interactive terminal can grant code-digest trust and data-egress consent, and enablement is scoped to one agent. Inspect the digest, hooks, destinations, data classes, and secrets before granting either. Disable or remove a plugin and restart long-lived Jazz processes to evict code that was already imported. See Plugins.
Before either the plugin or the built-in classifier runs, Jazz marks a command high-risk when it
is malformed or contains substitution, a file redirection, or a command name built from a
variable. That check reads syntax only; judging what a given program does is left to the
classifier or plugin. No classifier verdict can lower those. See
Approvals.
classify.command-risk is a policy hook, not a passive advisory. For an execute_command call whose
declared risk is unknown, its read-only or low-risk result can make the active policy skip an
approval prompt. Jazz sends the hook only the bounded command string, after the operator has
consented to that data class and destination. Statically rated tools, tool-set reachability,
explicit allowlists, the active tier, and the shell denylist remain host-enforced. Missing, invalid,
timed-out, or unavailable plugin classification falls back to Jazz's built-in classifier and then
to high-risk; failure never lowers risk.
This is the strongest control available, and it is stronger than any policy tier: an agent
whose toolset omits execute_command cannot run shell commands at all, regardless of
approval settings. Configure the toolset per agent rather than granting everything and relying
on the gate.
| Tier | Auto-approves |
|---|---|
unset / false |
Nothing. Every gated call asks, or is declined when nobody can answer |
read-only |
Reads, search, web requests, the agent's own todos/work state/scratchpad, subagents, shell classified inspect-only |
low-risk |
+ memory writes, reminders, triggers, compositions, shell classified low-risk |
high-risk |
+ writes, deletes, shell, unresolved unknown tools |
These tiers govern ordinary tool risk gates. HTTP requests and web fetches use their independent global HTTP approval policy below.
Leaving the tier unset is the safe default for unattended work because it grants nothing: a
workflow without autoApprove and jazz run without --approval-policy decline every gated
call. Interactive chat, where you are there to answer, starts in safe mode, which is the
low-risk tier: only high-risk calls ask. An autoApprove value Jazz does not recognize is an error,
never a tier. Opting into high-risk is always explicit: see
Running fully unattended.
Other tools above read-only are gated, including plain tools without a proposal half
(create_pdf, custom command tools). HTTP requests and web fetches instead run automatically
by default, including private destinations and calls after untrusted content. A global
network.httpApproval URL array requires one-call approval outside its grants regardless of
risk tier; each redirect must match too. Cross-origin credential stripping and response limits
remain active. Tool access restrictions still apply. An approval request is honored
only from the tool registered to make it, so a tool (or an MCP server) cannot forge one to run
another tool's execute half.
low-risk is narrower than it sounds. It adds three tools. Email, calendar, and
Obsidian are skills that shell out via execute_command (unknown), so prefer allowlisting
one binary over raising the whole tier:
// ~/.jazz/config.json
{ "autoApprovedCommands": ["himalaya", "khal"] }Matching uses a key parsed the way the shell reads the command (the binary, plus the next word
when it is not a flag), never a raw prefix. A command with control operators (&&, ||, ;,
|, &), command or process substitution, redirection, or a leading NAME=value assignment
has no key and always asks: git status does not also permit git status && rm -rf /,
git status $(rm x), git status > ~/.bashrc, or PAGER=x git status. Wrappers such as
sudo stay in the key. Full rules: Approvals.
A chat bridge, a public webhook, or a CI job reviewing fork PRs takes input from someone who is
not you. At high-risk, a message, or a prompt injection inside a web page the agent fetched
, can run arbitrary commands on that host. Use an allowlist of senders, keep the tier low, and
trim the toolset. See
Chat platforms → security.
Below high-risk, Jazz narrows what injected content can do through other tools: a model-chosen URL on
this machine or your network asks for approval unless it is in the global
network.allowPrivateHosts, secret values in every tool result are redacted before the model sees
them, outside content reaches the model labelled as untrusted, and once a run has read it, egress
tools other than HTTP requests and web fetches need approval.
See Secrets and egress.
- Do I understand what this will do, and is it reversible?
- Am I in the right directory, and are the paths correct?
- For
git push: the right remote and branch?
For untrusted work or unattended deployments, isolate rather than trust:
FROM node:20-alpine
RUN npm install -g jazz-ai
USER node
WORKDIR /home/node
CMD ["jazz"]Also consider a dedicated OS user for running Jazz, and separate service accounts (a bot GitHub account, a separate mailbox) so a mistake cannot reach your primary identity.
Jazz resolves every secret in this order, and uses the first hit:
- Environment variable:
OPENAI_API_KEY,ANTHROPIC_API_KEY,BRAVE_API_KEY, and so on. Nothing touches disk. Best for containers and CI. - OS keyring: macOS Keychain, or libsecret (
secret-tool) on Linux. Used automatically when available. Keys already sitting in~/.jazz/config.jsonare moved here on next start. Entries are scoped to the Jazz home (servicejazz.<hash of the home path>), so oneJAZZ_HOMEcannot read another's keys. ~/.jazz/config.json: the fallback when there is no keyring, e.g. a headless server with no session D-Bus. Jazz creates the file mode0600and repairs looser modes on load, but the keys are plaintext to anyone who can read that file (includingroot).
On a shared host, prefer 1 or 2. Set JAZZ_DISABLE_KEYRING=1 to force the file path.
The chatgpt provider uses an OAuth bundle rather than an API key. Hosted workflows can supply
the copied bundle in JAZZ_CHATGPT_CREDENTIAL; Jazz captures and removes that variable before
starting agent child processes, then stores the credential through the normal keyring/file
backend. When JAZZ_CHATGPT_CREDENTIAL_OUTPUT is configured, a successful refresh writes the
rotated bundle to that path with mode 0600 so the workflow can persist it. A run given only
JAZZ_CHATGPT_ACCESS_TOKEN holds no refresh token at all: Jazz removes that variable the same
way, never stores or refreshes the token, and fails with an authentication error once it expires.
Secrets resolved from the environment or the keyring are never written back into the config file. To check what is on disk:
cat ~/.jazz/config.json && ls -l ~/.jazz/config.jsonNote that ~/.jazz/history/ and ~/.jazz/logs/ are separate plaintext stores and are not
covered by the keyring: treat them as sensitive in their own right.
- Stop the run: double-Escape interrupts generation and any running tool; otherwise exit the process.
- Check what happened:
~/.jazz/logs/has every tool invocation with its arguments; credential-bearing fields are shown as[redacted:<name>]. - Recover: inspect
git statusandgit reflog, then restore only the affected paths or branch from a known-good commit. For non-Git files, use your backup or trash. - Report it: if the cause was Jazz acting without approval rather than an approval you granted, that is in scope.
- Tools & approval: how gating and risk tiers are enforced
- Tools reference: every tool and its tier
- Configuration:
envAllowlist,autoApprovedCommands - Local and air-gapped models: offline mode, local providers, and the network controls required for a real air gap
- Security questions: Discord · Discussions