Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt

Use this file to discover all available pages before exploring further.

Buttons is a tool that executes user-defined code by design. This page describes what the threat model covers, what it explicitly does not cover, and how to report a vulnerability.

​
What Buttons does by design

When you press a button, Buttons runs a subprocess (shell, Python, Node) or sends an HTTP request. There is no sandbox around that execution. A button that contains rm -rf / will run rm -rf /. This is intentional — it is the core feature. The security controls in Buttons are aimed at preventing unintended execution or escalation, not at sandboxing arbitrary code.

​
In-scope threats

ThreatControl
Path traversal via argument valuesPathEscape applied to URL path segments — see template encoding
Command injection via argument valuesArgs injected as env vars (BUTTONS_ARG_<NAME>), never interpolated into the shell body
SSRF via HTTP buttons targeting internal servicesPrivate network blocking by default — see SSRF protection
Credential leakage via run historypressed/*.json and state.db created with mode 0600
Unauthorized reads of button specs~/.buttons/ created with mode 0700
Query/JSON injection via argument valuesContext-aware encoding in URL and body templates

​
Out-of-scope threats

  • Malicious button specs: Buttons does not validate whether a button’s code is safe. If you import or run a button from an untrusted source, you are responsible for reviewing its contents.
  • Privilege escalation: Buttons runs as the invoking user. It does not attempt to drop privileges. If your agent runs as root, buttons run as root.
  • Side-channel attacks: Timing or memory side-channels are not in scope.
  • Third-party MCP tools: When a button wraps an MCP tool call, the security of that tool is the responsibility of the MCP server operator.

​
Assumptions

  • $PATH is trusted. Buttons resolves python3, node, sh, and other interpreters by name. If an attacker can modify $PATH, they can substitute a malicious interpreter.
  • ~/.buttons/ is user-private. The directory is created with mode 0700. On shared systems, confirm your umask does not override this.
  • The button creator is trusted. Buttons does not distinguish between a button you created and one an agent created on your behalf. Both execute with your permissions.

​
Vulnerability reporting

If you find a security vulnerability in Buttons, please report it privately rather than opening a public issue. Preferred: Open a GitHub Security Advisory on the repository. This keeps the report private until a fix is released. Alternative: Email bobak@autono.co with the subject line [SECURITY] Buttons vulnerability report. Please include:
  • A description of the vulnerability and its impact
  • Steps to reproduce
  • The version of Buttons you tested against
  • Any suggested mitigations if you have them
We aim to acknowledge reports within 2 business days and release a fix within 14 days for confirmed vulnerabilities.