docs(helm): expose the private-network MCP opt-out to operators - #3133
Merged
Conversation
Den's SSRF guard refuses to fetch private/reserved addresses on behalf of users, which is correct on hosted multi-tenant deployments. But a common enterprise topology puts Den inside the customer's private network with their MCP servers on private addresses, and there the guard blocks every internal server. The operator sees MCP_URL_BLOCKED and is told to "use a public HTTPS MCP URL or change the deployment's private-network policy through security review", with no indication that a supported opt-out exists. env.ts has provided DEN_ALLOW_PRIVATE_MCP_URLS=1 all along, but it appeared only in source, unit tests, and one eval flow: not in .env.example, not in the chart, not in any doc. Surface it in all three places so the fix is reachable without reading the source. Scoped to den-api only. den-api, den-web, and inference all envFrom the same ConfigMap, so adding the key there would inject an SSRF-bypass flag into two workloads that never read it; the value is emitted directly on the den-api container instead. Only den-api consumes allowPrivateMcpUrls (mcp-connections, plugin-system/store, enterprise-mcp-client-adapter, external-mcp-client). Nothing renders unless an operator opts in, so helm template with default values is byte-identical to the previous chart: no ConfigMap checksum change and no pod restart on upgrade. Blank, 0, and false render nothing; only "1" enables it, matching the trimmed string comparison in env.ts; any other value fails the render rather than guessing. url-guard.ts and env.ts are untouched.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Jul 25, 2026
benjaminshafii
added a commit
that referenced
this pull request
Jul 25, 2026
…ce (#3139) * docs(enterprise): document outbound network access and guard it in CI Enterprise networks block outbound connections by default and IT must approve each destination, but nothing in this repo listed what OpenWork needs to reach. Two destinations were named nowhere at all: - objects.githubusercontent.com, the redirect target of every release-asset download. Approving only github.com lets a download start and then fail partway through. - registry.npmjs.org, used by `npx -y openwork-ui-mcp` in packaged builds. Blocked, the UI-control MCP is silently unavailable while the app still opens. Add docs/enterprise/outbound-access.md for customer IT, in plain language, with a copy-pasteable minimum allowlist and a what-breaks-when-blocked column. Desktop client access is documented separately from self-hosted Den access because different teams approve them on different networks. Back it with docs/enterprise/outbound-access.json and scripts/check-outbound-access.mjs, wired into ci-tests.yml, so a feature that introduces a new destination must document its enterprise impact. The check also reports manifest entries that no longer exist in code, so the list cannot rot. Hosts reached indirectly (redirect targets, subprocesses, links, schema strings) are classified by kind and exempt from the staleness rule. Docs, one check script, one CI step, one package script. No product behavior, configuration, API, or chart surface changes. * docs(self-host): make the cloud catalog diagnostic actionable on-prem Settings > Debug runs a bounded initialize -> tools/list check against the managed openwork-cloud MCP entry. It carries an organization MCP bearer token, so the probe refuses to send that credential to an origin outside its trust list. DEFAULT_TRUSTED_ORIGINS holds only the hosted origins, so on every self-hosted deployment the check returns untrusted_endpoint and never runs. The escape hatch, OPENWORK_AGENT_DIAGNOSTICS_TRUSTED_ORIGINS, appeared in exactly two places in the repo: its own source file and its own test. The guidance an operator actually saw was "have the server administrator explicitly trust the development origin" -- which calls a production on-prem Den a development origin and never names the variable, so nobody could act on it. Name the variable in the operator action, and document it in the self-hosting guide with the real format rules enforced by configuredTrustedOrigins: bare origins, comma-separated, https except loopback, invalid entries ignored rather than failing open, additive to the hosted defaults. The docs state explicitly that this enables the diagnostic only and that Cloud MCP itself works without it, so operators do not read a skipped probe as a broken deployment. The trust model is deliberately unchanged: agent-context-cloud-probe.ts is untouched, so which origins are trusted cannot differ from before. Trusting the endpoint's own origin would be circular, since the probe exists to validate the very config that names it. Tests pin that an unlisted self-hosted origin still performs no fetch, and that the action keeps naming the variable. * docs(helm): expose the private-network MCP opt-out to operators Den's SSRF guard refuses to fetch private/reserved addresses on behalf of users, which is correct on hosted multi-tenant deployments. But a common enterprise topology puts Den inside the customer's private network with their MCP servers on private addresses, and there the guard blocks every internal server. The operator sees MCP_URL_BLOCKED and is told to "use a public HTTPS MCP URL or change the deployment's private-network policy through security review", with no indication that a supported opt-out exists. env.ts has provided DEN_ALLOW_PRIVATE_MCP_URLS=1 all along, but it appeared only in source, unit tests, and one eval flow: not in .env.example, not in the chart, not in any doc. Surface it in all three places so the fix is reachable without reading the source. Scoped to den-api only. den-api, den-web, and inference all envFrom the same ConfigMap, so adding the key there would inject an SSRF-bypass flag into two workloads that never read it; the value is emitted directly on the den-api container instead. Only den-api consumes allowPrivateMcpUrls (mcp-connections, plugin-system/store, enterprise-mcp-client-adapter, external-mcp-client). Nothing renders unless an operator opts in, so helm template with default values is byte-identical to the previous chart: no ConfigMap checksum change and no pod restart on upgrade. Blank, 0, and false render nothing; only "1" enables it, matching the trimmed string comparison in env.ts; any other value fails the render rather than guessing. url-guard.ts and env.ts are untouched. * docs(enterprise): name the current GitHub release-asset host Verified against a live OpenWork release asset: github.com now redirects release downloads to release-assets.githubusercontent.com, not objects.githubusercontent.com. An allowlist naming only the old host would still let downloads start and then fail partway through, which is the exact symptom this page exists to prevent. List both. release-assets.githubusercontent.com is what GitHub serves today; objects.githubusercontent.com stays documented for older clients and any staged rollback. * docs(self-host): document the private-network (semi air-gapped) deployment Most enterprise installs are not fully air-gapped. The common shape is laptops with internet plus VPN, and Den web and Den API inside the customer's private network. That split was undocumented, so every customer rediscovered its gotchas by hitting failures. Add a published page covering the two network paths separately, because different teams approve them: what the desktop must reach, what Den must reach (only MySQL and ghcr.io at pull time are hard requirements), and the three things that surprise operators, each with symptom, cause, and fix: - Internal MCP servers are refused by the SSRF guard until DEN_ALLOW_PRIVATE_MCP_URLS=1, with the security tradeoff stated. - The Settings > Debug cloud catalog probe is skipped because only hosted origins are trusted. It states explicitly that this affects the diagnostic only and Cloud MCP still works, so a skipped probe is not read as an outage, and that the variable must be set before launch because the in-app environment store strips OPENWORK_* keys. - Den's outbound self-check targets a public host by default and can be self-hosted with DEN_DIAGNOSTICS_ORIGIN. Also resolve a contradiction that decided whether IT opens one hostname or two. docs/org-install-links.md claimed "the desktop must be able to reach both origins"; resolveDenBaseUrls ignores an explicit API origin when a base URL is present and derives <baseUrl>/api/den, proven by the existing den-mcp-url test. Steady-state desktop traffic needs one origin. A separate API origin is only reachable-critical for the one-time install-link exchange, which builds its endpoint from the apiBaseUrl carried in the link, and for external MCP clients. Both docs now state their context instead of disagreeing. * docs(self-host): consolidate network, air-gap, and certificate guidance Promote Self-host from a small Start here group to a dedicated docs tab while preserving every existing start-here URL. Consolidate scattered network material into five focused published pages: air-gapped deployment, outbound network access, certificate trust and proxies, installer delivery, and network diagnostics. Keep the private-network topology page as the high-level entry. Make boundaries explicit instead of conflating them: - mounted installers solve installer delivery, not full product isolation; - desktop Chromium, spawned sidecars, Den containers, and MySQL use different trust surfaces; - Linux Electron may require NSS/user trust even when /etc/ssl is correct; - sslmode=require encrypts but is not certificate identity verification; - a skipped Cloud catalog diagnostic does not mean Cloud MCP is broken. Promote the machine-guarded outbound manifest into customer-facing docs, retain repository operator pages and their existing anchors, and slim the self-host/private-network overviews so there is one canonical owner per detail. The Helm and diagnostics READMEs remain authoritative for low-level mechanics. This branch is stacked on PRs #3131, #3132, #3133, and #3135. It changes docs and navigation only; no product, Helm template, environment, skill, or eval behavior changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
Den's SSRF guard (
ee/apps/den-api/src/capability-sources/url-guard.ts) refuses to fetch private/reserved addresses on behalf of users. On hosted multi-tenant Den that is correct and must stay.But a very common enterprise topology is: Den runs inside the customer's private network, and their MCP servers live on private IPs. There the guard blocks every internal MCP server by default. The operator sees
MCP_URL_BLOCKEDand:ee/apps/den-api/src/env.ts:352-359has provided the opt-out all along:But
DEN_ALLOW_PRIVATE_MCP_URLSappeared only in source, unit tests, and one eval flow. Not in.env.example. Not in the chart. Not in any doc. An operator hittingMCP_URL_BLOCKEDhad no supported way to discover the fix.What this adds
Discoverability only — the mechanism already existed.
ee/apps/den-api/.env.example— documented alongside the otherDEN_*MCP/network settings.packaging/helm/openwork-ee/values.yaml—config.public.allowPrivateMcpUrls, defaulted blank, grouped with the other MCP URL settings (mcpResourceUrl,mcpAdditionalResources,mcpClaimNamespace).packaging/helm/openwork-ee/README.md— extends the existing## Isolated Networkssection with what the guard does, the exact symptom, the YAML, and an explicit security warning that enabling it disables SSRF protection for external MCP connection URLs and is only appropriate where Den's network position and the set of people who can add MCP connections are both trusted.packaging/helm/openwork-ee/tests/private-mcp-urls.sh— new chart test, auto-discovered bypublish-ee-images.yml:96-100.url-guard.tsandenv.tsare untouched.Compatibility — this is the important part
helm templatewith default values is byte-identical to the current chart. Nothing renders unless an operator opts in, so there is no ConfigMap checksum change and therefore no pod restart on upgrade for existing self-hosted deployments.Verified by rendering
origin/devand this branch from separate worktrees and diffing:```
=== default render diff ===
IDENTICAL
=== CI-style render diff (--set ingress.enabled=true --set inference.enabled=true) ===
IDENTICAL
```
I deliberately did not follow the
DEN_PASSWORD_BREACH_SCREENING_ENABLEDpattern (configmap.yaml:19), which renders unconditionally — that would add a key to every existing deployment's ConfigMap.Value handling is fail-safe and matches the code exactly (
env.ts:359compares.trim() === "1"):0/false1true,yes, …)Scoped to den-api only
den-api.yaml:100-102,den-web.yaml:72-74, andinference.yaml:73-75allenvFromthe same main ConfigMap. Putting the key there would inject an SSRF-bypass flag into two workloads that never read it, so the value is emitted directly on the den-api container instead.Only den-api consumes
allowPrivateMcpUrls—mcp-connections.ts:110,1814,plugin-system/store.ts:3969,enterprise-mcp-client-adapter.ts:79,external-mcp-client.ts:460.Proven in the render with
--set inference.enabled=trueso the assertion is not vacuous:```
den-api.yaml DEN_ALLOW_PRIVATE_MCP_URLS occurrences: 1
den-web.yaml DEN_ALLOW_PRIVATE_MCP_URLS occurrences: 0
inference.yaml DEN_ALLOW_PRIVATE_MCP_URLS occurrences: 0
full render configMapKeyRef occurrences: 0
```
Tests run
```
helm lint packaging/helm/openwork-ee
1 chart(s) linted, 0 chart(s) failed
for t in packaging/helm/openwork-ee/tests/*.sh; do bash "$t"; done
PASS custom-ca.sh
PASS observability-env.sh
PASS private-mcp-urls.sh
helm template ... --set config.public.allowPrivateMcpUrls=true
correctly rejected 'true'
```
The new chart test asserts: default render has zero occurrences (the compatibility guarantee); enabled render has exactly one, as a direct
value: "1"with noconfigMapKeyRef; the flag lands on den-api and not on den-web or inference;0/false/blank render nothing; an unexpected value fails the render. It also asserts the removed intermediate ConfigMap name never reappears.Fraimz
Skipped, stated explicitly per AGENTS.md: chart,
.env.example, and docs only, with no runtime code path changed. The executable proof is the byte-identical render diff plus the chart test, both above.