DSH plugin trust boundaries: what to touch, where to refuse
The first security fact of plugin development: plugin code runs in the host process, and the framework does not sandbox your module. Sandbox modes constrain what confined subprocesses may write, not what a plugin may read or send.(source) So the boundary in DSH plugin is not "the framework stops you", but "you choose to refuse at a specific line".
DSH plugin: same process means full trust by default
The default is that you can do whatever the host can do. (source)
A plugin receives apply(ctx) and works through ctx.fs, ctx.web, and ctx.approval. Those are capability seams, not permission gates: they give consistent semantics and error classes, but nothing stops you from calling node:fs or fetch directly.
Three things follow. The boundary must be explicit in code, because the framework will not supply one. Bypassing a seam does not fail loudly; it quietly loses provenance, guards, and observability. And reviewing a plugin means asking "did it go around", not only "did it call the right API".
The rest of this article covers the four places where that judgment matters most.
Credentials: DSH plugin names in config, values in providers
Config should carry references, and resolved values should not be cached across operations. (source)
Credentials are split in two: settings and cordis.yml carry references such as environment variable names, while values belong to a provider. resolve runs per operation, checks provider storage first and environment layers second, and an empty stored value counts as absent.
Three habits worth fixing:
- Store the name —
apiKeyRef: 'OPENAI_API_KEY', never a key in a default value or a log line. - Resolve at the use site — do not keep the result in a long-lived variable; a rotated value should apply to the next request.
- Do not guess on failure — unconfigured means unconfigured, not "fall back to a test key".
Reading process.env directly still works, but you lose the source layer, the masked preview, and the consistent empty-value rule, which is exactly what you need while debugging.
Files: DSH plugin opaque identity and symlinks
Once you hold a target, the original path is gone, so symlink checks must precede resolve. (source)
The filesystem seam resolves a path into an FsTarget, whose targetKey is opaque: a local backend may use a realpath-like string, a remote one a workspace URI or file id. Consumers may display displayPath but should not parse targetKey to rebuild paths.
The security-critical part is symlinks. resolve() intentionally follows them to produce a stable identity, while lstat does not. A rule like "reject links pointing into system directories" therefore has to run before resolve; afterwards you can no longer tell a file from a link.
The same applies to writes. Guards such as createIfAbsent and replaceIfVersion protect against overwrites and races, not against where the path points. With untrusted path input, check first, then write.
Network: DSH plugin treats fetched content as data
A successful fetch says nothing about trust, and a non-2xx response is still a result. (source)
The seam treats HTTP status as part of the resource state: a 404 or 500 still returns a result with a status and a body, while WebError is reserved for resources that cannot be fetched or represented safely. At the same time, HTTP providers do not restrict destinations, so the model can send data to any URL it can reach.
Together, those mean three things after a fetch:
- Treat it as data — never execute fetched text as instructions, never splice it into the system prompt.
- Limit egress — before sending user data out, confirm the destination is allowed instead of following a link from the content.
- Bound the size — fetched content can be large, so truncate at a known limit before it enters later steps.
One more detail: redirects can land you on an unexpected host. Allowed redirects are handled by the backend, but cross-origin jumps require a new tool call rather than a plugin chasing links on its own.
Four DSH plugin places that must fail closed
Degrading here is far more dangerous than failing. (source)
| Place | Correct reaction | Why not degrade |
|---|---|---|
| Confinement | reject with SANDBOX_UNAVAILABLE | silent unconfined pass-through is never legal |
| Approval | refuse unless allowed-once | missing or throwing responders become unavailable |
| Credential lookup | return unconfigured | falling back to a guess bypasses authorization |
| Path checks | reject before resolve | identity is opaque once the target exists |
All four share a property: if they continue on failure, the user sees nothing unusual while the risk has already happened. The plugin author's job is not to keep things running at any cost, but to stop and say why.
A DSH plugin boundary self-check
Run this list before shipping; it catches most "works but unsafe" cases. (source)
- Search for
process.envreads of credentials and route them through a reference. - Search for direct filesystem writes and move them behind the seam with guards.
- Check where paths come from, and whether symlink or traversal checks run before resolve.
- Check how fetched text is used, and whether it is ever treated as an instruction.
- Inspect the failure branches of those four places for a
catchthat continues anyway.
Verification: five boundary attempts
Use a deliberately out-of-bounds plugin and confirm each refusal really happens. (source)
- Point a credential reference at a missing name and assert the plugin reports unconfigured instead of calling with an empty string.
- Target a symlink into a system directory and assert the pre-resolve check rejects before any write occurs.
- Fetch a URL returning 404 and assert a result with a status, then confirm the payload is handled as untrusted data.
- Remove the sandbox backend and run confined execution; assert
SANDBOX_UNAVAILABLEand that no command was spawned. - Register a throwing approval responder and assert the outcome is
unavailableand the caller denied the operation.
If step 2 writes anyway, the check ran after resolve; if step 4 executed the command, something swallowed the failure and degraded.
For the full credential resolution semantics, read credentials and committed changes; guards and patches are covered in filesystem patches and guards; per-call sandbox policy is in sandbox and argv wrapping.
One line to close: plugins are fully trusted in-process, so draw the boundary yourself; keep names in config, check paths before resolve, treat external content as data, and refuse rather than degrade at all four gaps.
FAQ
No: DSH plugin code runs in the host process, and sandbox modes govern only the file effects of confined subprocesses, not plugin modules; a plugin can still read files, read the environment, and open sockets. The boundary has to be written by the plugin, not assumed from the sandbox.
Use the seam, because DSH plugin credentials resolve through a reference. The reference keeps the name in config and the value in a provider, resolves per operation, and treats an empty stored value as absent; reading the environment directly loses the source layer and hot-reload behavior.
Because the DSH plugin targetKey is an opaque identity: a local backend uses a realpath-like string, a remote one may use a workspace URI. resolve follows symlinks to produce that identity, so a symlink check has to happen with lstat before resolve.
A DSH plugin must refuse at confinement, approval, credential lookup, and path checks. A missing sandbox must fail with SANDBOX_UNAVAILABLE, approval must require allowed-once, credentials must report unconfigured, and path checks must run before resolve.
Related Terms
- CredentialRef
- CredentialRef is a branded credential reference named after a POSIX-style environment variable, resolved against provider storage then environment layers.— DeepSeek Harness reference - User credentials
- FsTarget
- FsTarget is the stable identity a filesystem backend resolves, holding an opaque targetKey and a displayPath meant only for presentation.— DeepSeek Harness reference - Filesystem
- ApprovalOutcome
- ApprovalOutcome is the closed approval result: allowed-once permits the operation, while rejected, cancelled, and unavailable are all denials.— DeepSeek Harness reference - User approval
- SandboxMode
- SandboxMode is the file-effect policy for a confined process: read-only, workspace-write, or danger-full-access, with no bearing on network.— DeepSeek Harness reference - Process sandbox
Sources
- DeepSeek Harness reference - Filesystem· deepseek-ai
- DeepSeek Harness reference - User credentials· deepseek-ai