From 207a59aad48ea632e6e5d6fb580b12850069b5f7 Mon Sep 17 00:00:00 2001 From: Dax Raad Date: Wed, 14 Jan 2026 14:49:27 -0500 Subject: [PATCH] docs: add comprehensive security threat model and architecture documentation --- SECURITY.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/SECURITY.md b/SECURITY.md index 537834e4d..cd7e4525b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,71 @@ +# Security + +## Threat Model + +### Overview + +OpenCode is an AI-powered coding assistant that runs locally on your machine. It provides an agent system with access to powerful tools including shell execution, file operations, and web access. + +### No Sandbox + +OpenCode does **not** sandbox the agent. The permission system exists as a UX feature to help users stay aware of what actions the agent is taking - it prompts for confirmation before executing commands, writing files, etc. However, it is not designed to provide security isolation. + +If you need true isolation, run OpenCode inside a Docker container or VM. + +### Out of Scope + +| Category | Rationale | +| ------------------------------- | ----------------------------------------------------------------------- | +| **Server access when opted-in** | If you enable server mode, API access is expected behavior | +| **Sandbox escapes** | The permission system is not a sandbox (see above) | +| **LLM provider data handling** | Data sent to your configured LLM provider is governed by their policies | +| **MCP server behavior** | External MCP servers you configure are outside our trust boundary | + +### Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ User's Machine │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ OpenCode Process │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ +│ │ │ Agent │ │ Permission │ │ Storage │ │ │ +│ │ │ (LLM + │ │ System │ │ (~/.local/share │ │ │ +│ │ │ Tools) │ │ │ │ /opencode) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ ┌─────────────────────────────────────────────────────┐ │ │ +│ │ │ Project Directory (cwd) │ │ │ +│ │ └─────────────────────────────────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────┼──────────────────┐ │ +│ ▼ ▼ ▼ │ +│ ┌────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ External │ │ LLM │ │ MCP │ │ +│ │ Filesystem │ │ Providers │ │ Servers │ │ +│ └────────────┘ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + +Optional (user must opt-in): +┌─────────────────────────────────────────────────────────────────┐ +│ HTTP Server Mode │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Server (localhost:port) │ │ +│ │ - REST API endpoints │ │ +│ │ - WebSocket PTY │ │ +│ │ - SSE event stream │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Server Mode + +Server mode is opt-in only. When enabled, set `OPENCODE_SERVER_PASSWORD` to require HTTP Basic Auth. Without this, the server runs unauthenticated (with a warning). + +--- + # Reporting Security Issues We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.