[Refactor/Chore] Harden shellctl control-plane access against same-host shell jobs
- Dominant language
- TypeScript
- Stars
- 156k
- Forks
- 24.6k
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 610
Description
**AI disclosure**: This issue was drafted and analyzed with Codex using GPT-5.4. I have reviewed the analysis, and I am responsible for the content.
## Description
The new agent shell feature is currently intended for trusted users. Even under that trust model, shellctl should make its control-plane boundary explicit and resilient against same-host calls from shell jobs.
A shell job can execute arbitrary local processes. If the shellctl server is reachable on `127.0.0.1` and bearer auth is disabled, code running inside a shell job can call shellctl HTTP endpoints directly, bypassing the Dify shell layer checks that normally track job ids per session.
Current relevant behavior:
- `shellctl serve` defaults to `127.0.0.1:8765`.
- shellctl bearer auth is optional.
- Dify Agent calls shellctl through `DIFY_AGENT_SHELLCTL_ENTRYPOINT` and `DIFY_AGENT_SHELLCTL_AUTH_TOKEN`.
- The shell runner unsets `SHELLCTL_AUTH_TOKEN`, which is good and should be preserved.
- The Dify shell layer tracks job ids and prevents model/tool calls from inventing arbitrary job ids, but a local HTTP call to shellctl can bypass that layer when the shellctl API itself has no auth.
This is not an urgent vulnerability for the current trusted-user new agent rollout, but it is a control-plane hardening item before broader or less trusted use.
## Motivation
The defense boundary should not depend only on the agent layer when shell jobs can make local network requests. Requiring or strongly enforcing shellctl control-plane authentication in agent deployments reduces the risk of same-host SSRF-style self-calls and accidental exposure of shellctl management endpoints.
Recommended scope:
- Ensure production/new-agent deployments require shellctl bearer auth when shellctl is reachable over HTTP.
- Keep `SHELLCTL_AUTH_TOKEN` and equivalent control-plane credentials out of user shell environments.
- Consider failing fast in Dify Agent when `DIFY_AGENT_SHELLCTL_ENTRYPOINT` is configured but `DIFY_AGENT_SHELLCTL_AUTH_TOKEN` is empty in non-development modes.
- Document that unauthenticated shellctl is only acceptable for local development or fully trusted single-user setups.
## Additional Context
This issue is a follow-up from the CodeQL review of PR #38593, but it is not tied to a single original CodeQL line annotation. The line-level CodeQL annotations are tracked separately in #38610 and #38611.
This issue is about control-plane access hardening, not about changing the current trusted-user positioning of the new agent feature.
Contributor guide
Assessment
This issue has not been assessed yet.