From a7af5c1f8a9ea27102eac9e72f64dd97dbfefff3 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Sun, 29 Mar 2026 14:13:08 +0200 Subject: [PATCH] Improve security documentation --- docs/02-usage/070_security.md | 101 ++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 41 deletions(-) diff --git a/docs/02-usage/070_security.md b/docs/02-usage/070_security.md index f1366e17..5a1d5668 100644 --- a/docs/02-usage/070_security.md +++ b/docs/02-usage/070_security.md @@ -1,29 +1,77 @@ # Security Considerations -Security and protection against supply chain attacks are important to us, and we take this topic seriously. +Security is important to us, and we take this topic seriously. -Serena comes in two main variants with different security characteristics: +## Serena's Assumptions -- the **JetBrains-based variant**, which integrates with a running JetBrains IDE, and -- the **language-server-based variant** (the free variant), which can automatically acquire language-server dependencies on demand. +The current security model for Serena assumes: -## JetBrains Variant +- the local machine is trusted, +- the MCP client (i.e. the LLM) is trusted, +- the code repository being worked on is trusted, +- user configuration is trusted, +- package manager configuration (e.g. npm) for downloading additional dependencies (i.e. language servers when using Serena with the LSP backend) is trusted. -The JetBrains variant of Serena is safe by default. +Serena contains tools for executing shell commands and modifying files. +As such tools are, however, an essential part of coding agent workflows, they typically need to be made available. +Therefore, the only way to *fully* protect against unintended consequences is to use a [sandboxed environment](sandboxing) for running Serena. -At runtime, Serena does **not** download additional components and does **not** start extra helper processes beyond the Serena MCP server itself. It talks to the already running JetBrains IDE and relies on the IDE's own indexing and language intelligence. +## General Recommendations for Risk Reduction -This means that, from a supply-chain perspective, the JetBrains variant has a much smaller runtime attack surface than the language-server-based variant. +To reduce the risk of unintended consequences, we recommend that you: +- back up your work regularly (keep the project being worked on under version control), +- restrict the set of allowed tools via the [configuration](050_configuration), +- do not expose [Serena's network services](network-security) to untrusted networks. -## Language-Server Variant +If you do not fully the trust the client/the LLM, we additionally recommend to monitor tool executions carefully +(provided that your MCP client supports this). -The language-server-based variant supports many languages, including languages whose language servers are not typically preinstalled on a machine. For convenience, Serena can therefore download or install certain language-server dependencies on demand. +(sandboxing)= +## Sandboxing +Sandboxing is the most effective way to mitigate risks when using coding agents. +[Running Serena inside a docker container](docker) which only exposes the necessary files and tools to the agent is a good way to achieve this. + +While setting up a sandboxed environment may require some initial effort, we highly recommend it for all security-conscious users. + +(network-security)= +## Network Security + +Serena includes several network services: +- the Serena MCP server itself (when run in [HTTP or SSE mode](streamable-http) instead of stdio mode) +- the Serena Dashboard web server +- the Serena JetBrains Plugin server, which runs within the JetBrains IDE (when using the JetBrains language backend) +- the Serena Project Server (only started explicitly for [project querying](query-projects)) + +By default, these services accept connections from localhost only, which is a secure default for most users +(given our assumption that the local machine is trusted; see above). + +These services can be reconfigured to listen on other addresses, but doing so may have security implications. +If you need to allow connections from other machines, we recommend that you set up a secure networking environment +(e.g. using a VPN or SSH tunnels) and ensure that only trusted machines can connect to these services. + +## Supply Chain Security + +Serena has two language backends with different security characteristics: + +- the JetBrains-based variant, which integrates with a running JetBrains IDE, and +- the language-server-based variant (the free variant), which can automatically acquire language server dependencies on demand. + +While we can assume that JetBrains IDEs installed by the user do not pose a security risk, +language server dependencies (if not handled with care) could. +For convenience, Serena downloads or installs certain language server dependencies on demand. We treat this path as security-sensitive and have hardened it accordingly. -### How Serena Secures Downloaded Language-Server Dependencies +The most important supply chain protections are: -For language servers that download archives, binaries, VSIX packages, NuGet packages, or other release artifacts, Serena uses a hardened shared download path with the following protections: +- exact version pinning, +- hash verification, +- host restriction, +- and isolated Serena-managed installation directories. + +### Auto-Downloaded Language Server Dependencies + +For language servers that are auto-installed by downloading archives, binaries, VSIX packages, NuGet packages, or other release artifacts, Serena uses a hardened shared download path with the following protections: - **Pinned versions by default**: default downloads use exact versions instead of floating `latest` or nightly channels. - **Integrity verification**: downloaded artifacts are checked against pinned SHA256 hashes stored in Serena's source code. @@ -63,35 +111,6 @@ One important detail is that `uvx` ignores the lockfile when installing directly For the `ty` Python language server, Serena also uses an exact pinned version when invoking it through `uvx`. -### Our Assumptions - -The current security model for Serena's language-server variant assumes: - -- the local machine is trusted, -- the checked-out repository is trusted, -- user configuration is trusted, -- package-manager configuration such as npm config is trusted unless explicitly overridden, -- and the main risk to defend against is compromised or unexpectedly changing upstream artifacts. - -Under these assumptions, the most important supply-chain protections are: - -- exact version pinning, -- hash verification, -- host restriction, -- and isolated Serena-managed installation directories. - -## Operational Recommendations - -As fundamental abilities for a coding agent, Serena contains tools for executing shell commands and modifying files. Therefore, if the respective tool calls are not monitored or restricted, and execution takes place in a sensitive environment, there is a risk of unintended consequences. - -To reduce that risk, we recommend that you: - -- back up your work regularly, for example by using Git, -- monitor tool executions carefully, if your MCP client supports this, -- consider enabling read-only mode for analysis-only sessions by setting `read_only: True` in `project.yml`, -- restrict the set of allowed tools via the [configuration](050_configuration), -- and use a sandboxed environment for running Serena, for example by [using Docker](docker). - ```{dropdown} What Serena Downloads by Default for Language Servers :open: