Skip to content

Commit e4ff999

Browse files
authored
Merge pull request #59 from debugmcp/claude/refine-local-plan-EhmYo
docs(security): document trust model
2 parents 92e886b + 268ec20 commit e4ff999

1 file changed

Lines changed: 22 additions & 1 deletion

File tree

‎SECURITY.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,13 +50,34 @@ The following components are in scope for security reports:
5050
- Vulnerabilities in upstream debug adapters (debugpy, js-debug, CodeLLDB, Delve, netcoredbg) — report these to their respective maintainers
5151
- Denial of service via intentionally malformed DAP messages in a local-only deployment
5252
- Issues requiring physical access to the host machine
53+
- Reports that mcp-debugger can perform actions on the local filesystem or in spawned debuggees with the privileges of the invoking user. This is by design — see [Trust Model](#trust-model). Path checks in `get_source_context`, `set_breakpoint`, etc. are for usability (early validation feedback), not security.
54+
- Reports that `evaluate_expression` can be used to read files, make network calls, or run arbitrary code inside the debuggee. This is the tool's intended behavior; the debuggee is already running with the user's privileges.
55+
56+
## Trust Model
57+
58+
mcp-debugger is a debugger, not a sandbox. It runs as a process trusted at the level of its invoking OS user, driven by an MCP client (such as an AI agent) that the operator has chosen to trust at that same level. **The trust boundary is the deployment, not the tool.** This holds whether the MCP client is on the same machine over stdio or remote over SSE, and whether the debuggee is local or attached over DAP.
59+
60+
There are really two privilege scopes the MCP client inherits:
61+
62+
- On the **mcp-debugger host**, the MCP client can read any file the mcp-debugger process can read (`get_source_context`, DAP source requests) and spawn arbitrary processes (`create_debug_session` + `start_debugging`, `attach_to_process`).
63+
- On the **debuggee host** (which may be a remote machine reached via `attach_to_process`), the MCP client can execute arbitrary code inside the debuggee (`evaluate_expression`, `redefine_classes`).
64+
65+
These capabilities are intrinsic to being a debugger and cannot be removed without defeating the tool's purpose. In particular, `evaluate_expression` forwards a caller-supplied expression to the debug adapter, which evaluates it in the debuggee's runtime; deciding whether such an expression is "safe" is undecidable in general and not a property mcp-debugger attempts to enforce.
66+
67+
If you want to constrain what the MCP client can reach, constrain the mcp-debugger process — and any host running a debuggee it can attach to:
68+
69+
- **Containers.** Run the published `debugmcp/mcp-debugger` image with the workspace mounted at `/workspace`. The container boundary is the filesystem boundary.
70+
- **OS permissions.** Run mcp-debugger as a user with read access only to the source you want it to debug, and no access to secrets, SSH keys, credentials, etc. The kernel enforces the limits.
71+
- **Network exposure.** If running in SSE mode, treat the SSE port as a remote shell endpoint — anyone who can reach it inherits the mcp-debugger process's privileges. Bind to loopback or put it behind authenticated network access.
72+
- **Remote debuggees.** When using `attach_to_process` to debug a process on another host, the MCP client inherits that debuggee's privileges too. Apply the same containment reasoning there.
73+
- **MCP client trust.** Do not expose mcp-debugger to an MCP client that you trust less than the OS user mcp-debugger runs under.
5374

5475
## Security Design
5576

5677
mcp-debugger follows these security principles:
5778

5879
- **Process isolation**: Each debug session runs in a separate process
5980
- **No credential storage**: The server does not store or manage user credentials
60-
- **Input validation**: File paths and DAP messages are validated at system boundaries
81+
- **UX-level path validation**: File paths are checked for existence at request boundaries to give the MCP client immediate feedback on bad inputs. This is not an access-control mechanism — see [Trust Model](#trust-model).
6182
- **Least privilege**: CI workflows use minimal GitHub token permissions
6283
- **Supply chain hardening**: GitHub Actions are SHA-pinned, dependencies are audited, npm packages are published with sigstore provenance

0 commit comments

Comments
 (0)