The latest released minor version receives security fixes. Please upgrade to the most recent release before reporting an issue.

Please do not open a public issue for security problems.

Instead, use GitHub's private vulnerability reporting: Report a vulnerability. It goes straight to the maintainers and stays private until a fix is released.

Please include:

• A description of the issue and its impact.
• Steps to reproduce (a minimal proof of concept is ideal).
• Affected version(s) and platform.

We aim to acknowledge reports within 72 hours and to provide a remediation timeline after triage. We will credit reporters in the release notes unless you prefer to remain anonymous.

firstrun helps you understand a command before you run it. A few important points for your own threat model:

• The live preview runs the command. On linux/amd64, the preview executes the command under a ptrace tracer that neutralizes state-changing syscalls by redirecting them to a harmless no-op. It covers a broad set: file writes and creates, deletes, renames, mkdir/rmdir, truncate (path and fd based), chmod/chown (path and fd based), links, timestamps and extended attributes, connect, signals, mounts, privilege changes, kernel-module loads, and the io_uring/bpf/process_vm_writev bypass primitives. The command's non-mutating code still runs (it computes, reads files, allocates memory).
• It is not a complete sandbox. Two honest limits: (1) Network egress is only partially contained — firstrun blocks outbound connect (which stops the overwhelming majority of downloads and exfiltration, since TCP needs it), but a program could still send UDP datagrams (including DNS lookups) without connect, so a determined exfiltration over raw UDP is not blocked. (2) New or exotic syscalls outside the neutralized set would pass through. For these reasons firstrun is a strong aid for inspecting ordinary scripts, not a hardened sandbox for running code you already believe is hostile. Do not rely on it to safely detonate malware.
• Static analysis is best-effort. firstrun predicts effects from the command text. Commands whose targets come from variables or command substitution are flagged as dynamic, because the real targets are only known at run time.
• Narration may use a model you choose. With no key configured, explanations are generated entirely offline. If you set an API key (Anthropic/OpenAI) or point firstrun at a model, the command text (size-capped) is sent to that provider to write the explanation — never your files. Use --no-ai or a local Ollama for zero external egress.
• firstrun --yes and confirming "Run it for real" execute the command with your full privileges. Treat that the same as running it yourself.

If you find a way for the Block-mode preview to modify the filesystem, network, or process state on linux/amd64, that is a security bug — please report it privately using the process above.