Skip to content

Security: lvndry/jazz

SECURITY.md

Security Policy

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.


Reporting a vulnerability

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.

Supported versions

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.


Scope

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 / autoApprove tier
  • 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 (or autoApprove: 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.


How Jazz protects you

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.

The command denylist is not a sandbox

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.

Plugins are trusted code

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.


Running Jazz safely

Give each agent the fewest tools it needs

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.

Pick the lowest policy tier that lets the job finish

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.

Be deliberate on surfaces that accept input from other people

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.

Before approving, ask

  • 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?

Harden the host

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.

Know where your API keys live

Jazz resolves every secret in this order, and uses the first hit:

  1. Environment variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, BRAVE_API_KEY, and so on. Nothing touches disk. Best for containers and CI.
  2. OS keyring: macOS Keychain, or libsecret (secret-tool) on Linux. Used automatically when available. Keys already sitting in ~/.jazz/config.json are moved here on next start. Entries are scoped to the Jazz home (service jazz.<hash of the home path>), so one JAZZ_HOME cannot read another's keys.
  3. ~/.jazz/config.json: the fallback when there is no keyring, e.g. a headless server with no session D-Bus. Jazz creates the file mode 0600 and repairs looser modes on load, but the keys are plaintext to anyone who can read that file (including root).

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.json

Note 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.


If something goes wrong

  1. Stop the run: double-Escape interrupts generation and any running tool; otherwise exit the process.
  2. Check what happened: ~/.jazz/logs/ has every tool invocation with its arguments; credential-bearing fields are shown as [redacted:<name>].
  3. Recover: inspect git status and git reflog, then restore only the affected paths or branch from a known-good commit. For non-Git files, use your backup or trash.
  4. Report it: if the cause was Jazz acting without approval rather than an approval you granted, that is in scope.

Related

There aren't any published security advisories