| 1 | # Security Policy |
| 2 | |
| 3 | ## Supported Versions |
| 4 | |
| 5 | Reasonix security fixes are prioritized for the currently developed Go rewrite |
| 6 | and the current 1.x release line. |
| 7 | |
| 8 | | Version or branch | Security support | |
| 9 | | --- | --- | |
| 10 | | `main-v2` / 1.x releases | Supported | |
| 11 | | `v1` / 0.x legacy branch | Critical fixes only, where practical | |
| 12 | | Older releases, forks, or modified builds | Not covered unless the issue is reproducible upstream | |
| 13 | |
| 14 | If you are unsure whether a version is affected, report against the newest |
| 15 | released 1.x version and include the exact version or commit you tested. |
| 16 | |
| 17 | ## Reporting a Vulnerability |
| 18 | |
| 19 | Please report security issues privately. Do not open a public issue with exploit |
| 20 | details, secrets, crash dumps, or proof-of-concept payloads. |
| 21 | |
| 22 | Preferred reporting path: |
| 23 | |
| 24 | 1. Use GitHub private vulnerability reporting for this repository, if available. |
| 25 | 2. If private reporting is not available to you, open a minimal public issue |
| 26 | asking for a private maintainer contact path. Do not include exploit details |
| 27 | in that issue. |
| 28 | |
| 29 | Please include: |
| 30 | |
| 31 | - Affected Reasonix version, commit, operating system, and installation method. |
| 32 | - The feature or surface involved, such as CLI, desktop app, HTTP `serve`, bot |
| 33 | gateway, MCP plugin, built-in tool, updater, or configuration loading. |
| 34 | - Clear reproduction steps using dummy credentials and non-sensitive files. |
| 35 | - The expected impact, such as secret disclosure, arbitrary file access, |
| 36 | command execution, sandbox escape, authentication bypass, or supply-chain risk. |
| 37 | - Any relevant logs with API keys, tokens, local paths, and personal data |
| 38 | redacted. |
| 39 | |
| 40 | Do not send real provider API keys, bot credentials, OAuth tokens, private |
| 41 | workspace files, or third-party user data. |
| 42 | |
| 43 | ## Security Boundaries |
| 44 | |
| 45 | Reasonix is a local coding agent. Many features intentionally operate on the |
| 46 | user's local machine and workspace, including file reads, file writes, shell |
| 47 | commands, MCP plugins, language servers, bot sessions, and model-provider |
| 48 | requests. A finding is security-relevant when it crosses a supported boundary or |
| 49 | bypasses an explicit guard. |
| 50 | |
| 51 | Supported boundaries include: |
| 52 | |
| 53 | - Workspace confinement for file operations that are documented or implemented |
| 54 | as workspace-scoped. |
| 55 | - Permission checks for tool calls, shell commands, file writes, and approvals. |
| 56 | - Sandbox behavior for built-in shell execution where the platform supports it. |
| 57 | - Secret handling for provider keys, bot credentials, OAuth tokens, plugin |
| 58 | headers, and credential-store fallback files. |
| 59 | - HTTP `serve` protections, including the launch token every state-changing |
| 60 | request requires when authentication is off, localhost binding assumptions, |
| 61 | JSON-only state-changing requests, and CORS restrictions. |
| 62 | - Desktop and bot session isolation, including per-workspace session metadata |
| 63 | and configured bot allowlists. |
| 64 | - Updater, install, and release verification paths. |
| 65 | |
| 66 | The following are normally treated as trusted local/operator-controlled inputs |
| 67 | unless another bug lets an untrusted actor supply them: |
| 68 | |
| 69 | - CLI arguments and text typed directly by the local user. |
| 70 | - The user's own configuration under the Reasonix home directory. |
| 71 | - Explicit `@path` references supplied by the local user to attach local files. |
| 72 | - MCP servers, language servers, hooks, and slash commands installed, enabled, |
| 73 | or approved by the local user. |
| 74 | - Provider base URLs and model names configured by the local user. |
| 75 | |
| 76 | The following can be security issues when reachable by an untrusted actor or |
| 77 | when they bypass the intended boundary: |
| 78 | |
| 79 | - Reading or writing files outside the configured workspace without explicit |
| 80 | local-user intent. |
| 81 | - Following symlinks or path traversal to escape workspace confinement. |
| 82 | - Running shell commands or external tools without the required permission gate. |
| 83 | - Leaking credentials, environment variables, prompt history, local files, or bot |
| 84 | messages to logs, model providers, MCP servers, crash reports, or telemetry. |
| 85 | - Allowing a website to drive the local HTTP server through CSRF, CORS, or |
| 86 | content-type bypasses. |
| 87 | - Letting a bot user outside the configured allowlist submit prompts, approve |
| 88 | tools, or access a project workspace. |
| 89 | - Trusting unverified update artifacts, plugin definitions, or downloaded |
| 90 | binaries. |
| 91 | |
| 92 | ## Project Configuration |
| 93 | |
| 94 | Files that arrive with a workspace are untrusted input: `reasonix.toml`, |
| 95 | `.reasonix/settings.json`, `.mcp.json` and the project `.env`. Cloning a |
| 96 | repository is not a decision to trust its author, so these files may narrow |
| 97 | what the user configured and never widen it. |
| 98 | |
| 99 | | Setting | What a workspace file may do | |
| 100 | | --- | --- | |
| 101 | | `sandbox.bash` | Move `off` to `enforce`, never back | |
| 102 | | `sandbox.network` | Move `true` to `false`, never back | |
| 103 | | `sandbox.forbid_read` | Add to the user's list | |
| 104 | | `sandbox.allow_write`, `sandbox.workspace_root` | Apply only when they resolve inside the workspace, symlinks followed; `${VAR}` in any sandbox path expands from the process environment only | |
| 105 | | `permissions.deny`, `permissions.ask` | Add to the user's rules | |
| 106 | | `permissions.mode`, `permissions.allow`, `permissions.allow_dynamic_bash` | Nothing | |
| 107 | | `desktop.default_tool_approval_mode` | Nothing | |
| 108 | | `[network]` proxy settings, `[bot]` | Nothing | |
| 109 | | `[[providers]]` | Declare them; they stay out of use until approved, and model settings naming them fall back to the user's | |
| 110 | |
| 111 | An "always allow" answer, or extra write access, granted in a workspace is |
| 112 | stored under the Reasonix home, not in the workspace. |
| 113 | |
| 114 | Programs a workspace names for the host to run stay off until the user |
| 115 | approves them for that workspace: |
| 116 | |
| 117 | - Hooks, language server commands, `tools.search.rg_path`, |
| 118 | `tools.shell.path` and `[browser]` launch settings are approved with |
| 119 | `reasonix trust`, or for hooks from the desktop hooks settings. |
| 120 | - An approval is stored under the Reasonix home with a digest of the |
| 121 | declaration and of the workspace files it names; any change needs approval |
| 122 | again. Approvals and grants belong to one workspace folder. |
| 123 | - Hooks and language servers are checked against their approval again before |
| 124 | each start, and refused if a file they name changed, appeared or now |
| 125 | resolves elsewhere. |
| 126 | - A single program path (`tools.shell.path`, `tools.search.rg_path`, |
| 127 | `browser.chrome_path`) may not point into the workspace, an `allow_write` |
| 128 | root, a temporary directory or a toolchain cache the bash jail leaves |
| 129 | writable, and may not climb with `..`; its approval covers the program |
| 130 | file's content. |
| 131 | - Without an interactive frontend they stay off. |
| 132 | - MCP servers a workspace declares stay off until the user enables that |
| 133 | declaration for that workspace. |
| 134 | |
| 135 | A project value that is not applied is reported as a load warning with the |
| 136 | reason. A way for workspace files to widen any of the above without the |
| 137 | user's approval is a security issue. |
| 138 | |
| 139 | ## `@` File References |
| 140 | |
| 141 | Reasonix supports `@path` references so users can include local files and images |
| 142 | in a prompt. This is intentional local functionality, but implementations must |
| 143 | preserve these invariants: |
| 144 | |
| 145 | - In workspace-scoped sessions, relative and absolute paths must resolve under |
| 146 | the active workspace root before file content is read or attached. |
| 147 | - Path traversal such as `..` must not escape the workspace root. |
| 148 | - Symlinks must not be usable to bypass the intended workspace boundary. |
| 149 | - Unscoped local CLI compatibility must not be exposed to remote, bot, or |
| 150 | browser-controlled inputs unless an equivalent workspace boundary is applied. |
| 151 | - File content should be size-limited and binary content should not be dumped as |
| 152 | prompt text. |
| 153 | |
| 154 | Static analysis alerts about path expressions should be triaged against these |
| 155 | rules: user-controlled path data is expected, but the access must either stay |
| 156 | inside the configured workspace or be clearly limited to trusted local CLI use. |
| 157 | |
| 158 | ## Out of Scope |
| 159 | |
| 160 | The following reports are usually out of scope unless they demonstrate a bypass |
| 161 | of one of the boundaries above: |
| 162 | |
| 163 | - A local user intentionally asks Reasonix to read, edit, or send their own |
| 164 | files to a configured model provider. |
| 165 | - A local user installs or enables a malicious MCP server, hook, slash command, |
| 166 | language server, or shell command and then grants it permission. |
| 167 | - A configured model provider, proxy, or MCP server receives data the user |
| 168 | intentionally sent to it. |
| 169 | - Denial-of-service issues that only affect the local user's own session and do |
| 170 | not corrupt files, leak secrets, or bypass permissions. |
| 171 | - Issues requiring administrator/root access on the user's machine before |
| 172 | interacting with Reasonix. |
| 173 | - Vulnerabilities in third-party services, models, proxies, or plugins that are |
| 174 | not caused by Reasonix behavior. |
| 175 | |
| 176 | ## Coordinated Disclosure |
| 177 | |
| 178 | This is a community-maintained project. Maintainers will make a best-effort |
| 179 | assessment, ask follow-up questions when needed, and coordinate fixes before |
| 180 | public disclosure for confirmed vulnerabilities. |
| 181 | |
| 182 | Please give maintainers reasonable time to investigate and release a fix before |
| 183 | publishing exploit details. If you plan to disclose on a timeline, include that |
| 184 | timeline in your initial report. |
| 185 |