URL egress inventory
Where NodeTool’s server can be told to open an outbound request, who tells it, and what decides whether it may.
A URL that reaches this process is rarely typed by the person who owns the
machine. It rides in on a media ref inside a workflow, in a provider’s result
body, on a chat client’s attachment, or straight out of a model that read
someone else’s web page a moment ago. A bare fetch(uri) on any of those is
the server making a request on a stranger’s behalf from inside the perimeter,
which is how http://169.254.169.254/latest/meta-data/ gets read.
The machine-readable list is
packages/runtime/tests/url-egress-inventory.ts; the audit that keeps it honest
is url-egress-audit.test.ts beside it. Run both with
npm run test --workspace=packages/runtime -- url-egress.
The policy
Default: https, to a host that is not a loopback, link-local, RFC1918,
CGNAT or benchmarking address — and every redirect hop re-checked.
safeFetch in packages/runtime-core/src/safe-url.ts is that policy as a
function, and it is the only thing that counts as protection. isSafePublicHttpsUrl
and friends are predicates: a predicate can refuse an initial URL, but a public
host that answers 302 Location: http://127.0.0.1:6379/ walks past one.
Media refs go through fetchExternalMedia
(packages/runtime/src/external-media-fetch.ts), which is safeFetch plus one
documented opt-out (below). Audio loading in
packages/audio-nodes/src/lib/audio-wav.ts delegates to loadMediaRefBytes in
packages/runtime/src/media-ref-bytes.ts, whose HTTP fallback calls
fetchExternalMedia and checks every redirect hop.
The lean sandbox fetch bridge in packages/sandbox-runtime/src/index.ts
uses safeFetch under the default public HTTPS policy, with per-run request and
response limits. Guest code cannot enable private network or host filesystem
access in this host.
The full sandbox fetch bridge runs its own policy on purpose: plain http is
allowed, and a host — never guest code — may waive the address check for a node
that replaces a trusted lib.http node. It reads the same address table.
One address table
isBlockedIpLiteral in packages/runtime-core/src/safe-url.ts decides which literals are
internal. It covers IPv4 (loopback, 0.0.0.0/8, RFC1918, 169.254/16, CGNAT,
198.18/15), the alternate spellings the WHATWG parser normalizes for us
(decimal, hex, octal, short form), IPv6 loopback/unspecified/ULA/link-local, and
the IPv6 forms that carry an IPv4 inside them — IPv4-mapped, IPv4-compatible,
6to4, NAT64.
Four tables existed before: this one, the sandbox’s in
packages/agents/src/network-guard.ts (which now imports it), a private copy
inside unified-websocket-runner.ts (deleted — it allowed http and screened
only the first URL), and isSafeHttpUrl in together-nodes /
atlascloud-nodes, which survive as local predicates in front of a protected
fetch. The audit fails if a private copy comes back.
DNS rebinding
Decision: not defended in-process; the deployment’s egress control is the
boundary. A name that passes the address check can resolve to a private
address a millisecond later, and this process does not choose the address
fetch connects to — pinning one means resolving ourselves and dialing an IP
with a Host header, which breaks TLS verification and virtual hosting for
every provider CDN we download from.
One exception, and it earns the round trip: when the URL is handed to a
separate process that opens its own sockets, assertResolvedHostAllowed
(packages/agents/src/network-guard.ts) resolves the name and refuses a
blocked answer first. yt_dlp is the surface that uses it.
Every inventory entry records which of the two it is, in dnsRebinding. An
entry that claims resolve-and-check must call the resolver.
The self-hosted opt-out
NODETOOL_ALLOW_PRIVATE_MEDIA_FETCH=1 turns the guard off for media-ref
fetches — and for nothing else. It exists for an install that genuinely serves
media off its own LAN (http://nas.local/clip.mp4). It is read per call, so it
takes effect without a restart, and it is off by default. See
configuration.md.
Guarded surfaces
Entity reference images in packages/core-nodes/src/nodes/entity.ts resolve
URI-backed media through loadMediaRefBytes before creating an owned asset.
Package references use the processing context’s package resolver. Remote URLs
use the shared media egress policy, including redirect checks.
Everything here fetches a URL somebody else chose, through the protected fetch.
| Surface | File | URL comes from |
|---|---|---|
| media ref → bytes (Python bridge + TS nodes) | packages/runtime/src/media-ref-bytes.ts |
workflow |
| AudioRef → shared media resolver | packages/audio-nodes/src/lib/audio-wav.ts |
workflow |
| Model3DRef / ImageRef → bytes | packages/video-nodes/src/nodes/model3d/utils.ts |
workflow |
| Model bytes → bytes (shared resolution) | packages/nodes-utils/src/model-bytes.ts |
workflow |
| chat source images | packages/websocket/src/websocket-client-session.ts |
chat client |
| workflow output auto-save | packages/project-services/src/asset-autosave.ts |
workflow |
| asset ref → bytes on export | packages/websocket/src/lib/asset-export.ts |
chat client |
| Openverse import → asset | packages/websocket/src/lib/openverse.ts |
provider response |
save_asset / view_image |
packages/agents/src/capabilities/assets.ts |
model |
yt_dlp download |
packages/agents/src/capabilities/media.ts |
model |
| Apify run artifacts → assets | packages/agents/src/apify/assets.ts |
provider response |
render_sketch / nodetool sketch render layer images |
packages/agents/src/capabilities/sketches.ts, packages/cli-sketch/src/commands/sketch-render.ts |
sketch document |
| Google Fonts family resolution (timeline) | packages/timeline/src/fonts/google-fonts-fetch.ts |
workflow |
| Reve reference image | packages/reve-nodes/src/reve-base.ts |
workflow |
| HF pipeline media input | packages/huggingface-nodes/src/huggingface-base.ts |
workflow |
| FAL media upload | packages/fal-nodes/src/fal-base.ts |
workflow |
| Replicate files upload | packages/replicate-nodes/src/replicate-base.ts |
workflow |
| OpenAI media input | packages/llm-nodes/src/nodes/openai.ts |
workflow |
| Together image and endpoint result downloads | packages/runtime/src/providers/together-provider.ts |
provider response |
| UberLLM generated image downloads | packages/runtime/src/providers/uberllm-provider.ts |
provider response |
| Together asset resolution | packages/together-nodes/src/together-base.ts |
workflow |
| AtlasCloud media pass-through | packages/atlascloud-nodes/src/atlascloud-factory.ts |
workflow |
| AtlasCloud prediction downloads | packages/runtime/src/providers/atlascloud-transport.ts |
provider response |
| Higgsfield uploads and prediction downloads | packages/runtime/src/providers/higgsfield-transport.ts |
provider response |
| useapi.net Google Flow and Dreamina result downloads | packages/runtime/src/providers/useapi-provider.ts |
provider response |
| vgenv MiniMax H3 result downloads | packages/runtime/src/providers/vgenv-provider.ts |
provider response |
| ToAPIs GPT Image and Seedance 2 result downloads | packages/runtime/src/providers/toapis-provider.ts |
provider response |
| Z.ai GLM-Image and CogVideoX result downloads | packages/runtime/src/providers/zai-provider.ts |
provider response |
| Alibaba Model Studio Wan, Qwen-Image and Qwen TTS result downloads | packages/runtime/src/providers/alibaba-provider.ts |
provider response |
| Kling AI video and image result downloads | packages/runtime/src/providers/kling-provider.ts |
provider response |
| BytePlus Seedance video result downloads | packages/runtime/src/providers/byteplus-provider.ts |
provider response |
KIE endpoint result downloads (downloadMedia) |
packages/runtime/src/providers/kie-endpoint.ts |
provider response |
| Topaz result downloads and video part uploads | packages/runtime/src/providers/topaz-provider.ts |
provider response |
| Gemini node video download | packages/llm-nodes/src/nodes/gemini.ts |
provider response |
default provider downloadMedia for endpoint results |
packages/runtime/src/providers/base-provider.ts |
provider response |
| provider result downloads | packages/runtime/src/providers/{fal,replicate,kie,topaz,meshy,rodin,minimax,evolink,gemini,anthropic}-provider.ts |
provider response |
| durable FAL output recovery | packages/websocket/src/generation-recovery.ts |
provider response |
| MCP OAuth Client ID Metadata Document fetch | packages/websocket/src/oauth/cimd.ts |
model/client (an MCP client’s self-hosted client_id URL) |
| external MCP server (HTTP transport) | packages/websocket/src/external-mcp.ts |
operator (a user’s own MCP server URL; guarded under the cloud profile, loopback allowed on a local install) |
| custom OpenAI-compatible provider | packages/runtime/src/providers/custom-openai-provider.ts, checked on save in packages/websocket/src/custom-providers.ts |
operator (a user’s own base URL; guarded under the cloud profile, loopback allowed on a local install) |
| Azure OpenAI provider | packages/runtime/src/providers/azure-openai-provider.ts |
operator (a user’s own Azure resource endpoint; guarded under the cloud profile, private endpoints allowed on a local install) |
| Amazon Bedrock chat media | packages/runtime/src/providers/bedrock-provider.ts |
chat client (https URLs on image and document parts; API calls use the fixed regional AWS host) |
The provider row is eleven files, each downloading a URL a provider’s response
named — plus one reading a URL the caller’s own message named
(video-frame-fallback.ts, which fetches a video content part so libav can
sample stills from it for a model that cannot read video):
packages/runtime/src/providers/fal-provider.tspackages/runtime/src/providers/replicate-provider.tspackages/runtime/src/providers/kie-provider.tspackages/runtime/src/providers/topaz-provider.tspackages/runtime/src/providers/meshy-provider.tspackages/runtime/src/providers/rodin-provider.tspackages/runtime/src/providers/minimax-provider.tspackages/runtime/src/providers/evolink-provider.tspackages/runtime/src/providers/gemini-provider.tspackages/runtime/src/providers/anthropic-provider.tspackages/runtime/src/providers/video-frame-fallback.ts
The explicitly installed pack adapter in
packages/server-feature-packs/src/index.ts injects safeFetch and the current
run’s cancellation signal into its execution context. Pack transport uses the
default public HTTPS policy and the authenticated tenant’s credentials.
The minimal HTTP workflow node in packages/nodes-core/src/index.ts passes
workflow URLs through safeFetch. The OpenAI-compatible text adapter in
packages/runtime-core/src/text-provider.ts and the optional Anthropic adapter
in packages/provider-anthropic/src/index.ts inject safeFetch into their
official SDK transports. Their endpoint URLs are operator-configured and carry
the authenticated tenant’s provider key. Each request and redirect hop must use
public HTTPS under the default egress policy.
Screening code itself: packages/runtime-core/src/safe-url.ts,
packages/runtime/src/external-media-fetch.ts,
packages/agents/src/network-guard.ts, packages/agents/src/apify/policy.ts.
The full runtime compatibility export in
packages/runtime/src/providers/safe-url.ts delegates to runtime-core and opens
no request. The guest bridge is packages/agents/src/js-sandbox.ts.
Exemptions
Dreamina browser requests.
packages/runtime/src/providers/dreamina-provider.ts runs API and upload
requests inside the user’s logged-in Dreamina browser tab. Cookies stay in
that tab. Server-side result downloads use fetchExternalMedia, which checks
each redirect hop and sends no Dreamina credentials.
ChatGPT browser requests.
packages/runtime/src/providers/chatgpt-provider.ts runs every chatgpt.com
request inside the user’s logged-in ChatGPT tab, including generated-image
downloads. Cookies and the session token stay in that tab. An input image given
as a URL is fetched server-side with fetchExternalMedia, which checks each
redirect hop and sends no credentials.
Gemini web browser requests.
packages/runtime/src/providers/gemini-web-provider.ts runs every
gemini.google.com request inside the user’s logged-in Gemini tab. The browser
itself loads generated media with the user’s Google cookies, through
ExtensionTab.download. It loads only URLs that the Gemini response named: a
https://lh3.googleusercontent.com/gg-dl/ image or a
https://contribution.usercontent.google.com/download video. A chat input
image given as a URL is fetched server-side with fetchExternalMedia, which
checks each redirect hop and sends no credentials.
Fixed provider hosts. The URL is a constant in this repo, at most
with a path or query interpolated — api.elevenlabs.io, fal.run,
generativelanguage.googleapis.com, the OAuth token endpoints, the codegen
schema fetchers. Screening them would refuse nothing and would break an
install whose configured endpoint is deliberately internal. They carry the
provider’s own credential, so the rule that matters for them is the opposite
one: a URL that is not fixed must not inherit that credential. Each is listed
in the data module with its auth scope.
A region setting (MINIMAX_REGION, KIMI_REGION, KLING_REGION,
DASHSCOPE_REGION, ZAI_REGION) picks one of two constant hosts, so those
providers stay fixed hosts. DASHSCOPE_BASE_URL, BYTEPLUS_ARK_BASE_URL and
HF_ENDPOINT name an operator-configured host instead. They are the same case
as a configured embedding or storage endpoint: the setting holder picks the
host and receives the provider credential there. HF_ENDPOINT moves Model
Manager downloads, Hub search, llama.cpp GGUF downloads and Transformers.js
model downloads to a mirror, and the HF token goes with them.
FAL webhook verification fetches only
https://rest.fal.ai/.well-known/jwks.json. It sends no credentials, aborts
after five seconds, coalesces concurrent refreshes, and caps key-cache freshness
at 24 hours.
Package media (packages/config/src/package-media.ts) downloads example media
listed in a shipped manifest. It accepts only a manifest base on
https://media.nodetool.ai, names each object by its SHA-256, rejects
redirects, sends no credentials and checks the bytes against the manifest’s
hash and size.
Deliberately private hosts. Reaching an internal address is the feature:
-
packages/project-services/src/cloud-origin.ts— the cloud server a native app signed in to, which the app names when it hands its bundled local server a short-lived access token for a transfer. A self-hosted server can sit on the LAN. Plain http is allowed only to loopback. Every request must be on that origin and no redirect is followed, so the token reaches no other host. ThecloudTransferrouter that uses it answers only on a local server. -
packages/whisper-cpp/src/whisper-server-provider.ts— the operator’sWHISPER_CPP_SERVER_URL, normally localhost or the LAN. This local-only provider uses native fetch, following the llama.cpp server provider’s policy. Requests carry audio and transcription options without provider credentials. -
packages/integration-nodes/src/nodes/stable-diffusion-cpp.ts— the graph author selects a runningsd-server, normally localhost or the LAN. Requests send no credentials and reject redirects. Job polling and cancellation stay on the configured server, ignoring response-provided URLs. The cloud profile excludeslib.stable_diffusion_cpp.GenerateImageby default. packages/runtime/src/providers/sdcpp-provider.ts— the stable-diffusion.cpp provider calls only thesd-serverit starts on127.0.0.1, at a port it picked. Requests send no credentials and reject redirects. Job polling uses URLs built from the job id. The cloud profile excludes this provider.packages/runtime/src/providers/wan2gp-client.ts— a Wan2GP server, named byWAN2GP_MCP_URLor alib.wan2gpnode’s server URL, normally localhost or the LAN. Requests send no credentials and reject redirects. A media transfer ticket from the server must be a relative URL under/wangp_api/that resolves to the configured origin. The cloud profile excludes thewangpprovider and thelib.wan2gpnodes.packages/websocket/src/finetune/ollama-capture.tsandpackages/websocket/src/finetune/openai-capture.ts— fetch seams that the offlinefinetune-datascript injects into the Ollama, OpenRouter and llama.cpp providers to record each exchange. The URL is the provider’s own:OLLAMA_API_URL,FINETUNE_LLAMA_CPP_URLor OpenRouter’s fixed host, all set by the operator. No caller or model supplies one.packages/runtime/src/providers/wan2gp-server.ts— polls only the Wan2GP server it started on127.0.0.1, at a port it picked, until that server answers. The cloud profile excludes thewangpprovider and thelib.wan2gpnodes that start it.packages/runtime/src/providers/comfy-gpu-models.ts,packages/runtime/src/providers/comfy-template-models.tsandpackages/runtime/src/providers/comfy-fetch.tsinject retry-aware fetch into the Comfy SDK. The SDK selects request URLs, including output downloads, using its default cloud endpoint or operator configuration. These transports do not screen URLs.comfy-fetch.tsupgradeshttp://cloud.comfy.orgjob links to https and sends the API key only tohttps://cloud.comfy.org. Deployment egress controls govern redirects and resolved addresses.packages/runtime/src/comfy-executor.ts— a ComfyUI server, normally localhost or the LAN, so screening private addresses would refuse the ordinary case. The address is the node’sendpointproperty, so the graph author picks it, andlib.comfy.RunWorkflow/lib.comfy.RunWorkflowOnWorkerare allowlisted on the cloud profile.packages/integration-nodes/src/nodes/comfy-graph-cloud.ts,packages/integration-nodes/src/nodes/comfy-server-transport.ts,packages/integration-nodes/src/nodes/comfy-server-status.ts,GET /api/comfy/nodes, andGET /api/comfy/server-status— a self-hosted ComfyUI named by theCOMFY_SERVER_URLsetting. It is normally localhost or the LAN, the same case ascomfy-executor.ts, and the setting holder picks the address.packages/integration-nodes/src/nodes/comfy-worker-transport.ts— a NodeTool worker named by theCOMFY_WORKER_URLsetting. The setting holder picks the address, the same case asCOMFY_SERVER_URL.packages/integration-nodes/src/nodes/comfy-sdk.ts— the Comfy API v2 transport.@comfyorg/sdkopens the socket. Forlib.comfy.RunWorkflowOnCloudit opens against the constanthttps://cloud.comfy.org, unlessCOMFY_BASE_URLin the server’s environment names another deployment, which is the documented way to point it at a localcomfy-api-proxyon127.0.0.1:8189. The same transport carries the v2 paths of the other two nodes, where the base URL is the operator’s: theendpointproperty oflib.comfy.RunWorkflowwhen itsapiisv2, and the HTTP origin derived from theworker_urloflib.comfy.RunWorkflowOnWorker. Those are normally localhost, the LAN, or a rented worker, the same case ascomfy-executor.tsabove. The user’sCOMFY_API_KEYor the worker’s bearer token rides as anAuthorizationheader, and the SDK attaches it only to requests on the client’s own origin: a job’surls.self/cancel/eventslink resolves against that origin, and a signed output URL on another origin is fetched without the key.packages/runtime/src/providers/comfy-gpu-models.ts,packages/runtime/src/providers/comfy-template-models.ts— the retry wrapper handed to@comfyorg/sdk. It sends the SDK’s own requests. No caller, provider or model names the base URL, because each client takes only an API key and uses the SDK’s default.-
packages/agents/src/capabilities/web.ts—BROWSER_URL, the operator’s screenshot service. Every model-named URL that file fetches goes throughsafeFetch; this one is the operator’s own.With no
BROWSER_URL,take_screenshotrenders the page in a local headless Chrome instead (packages/agents/src/capabilities/local-browser.ts), which is egress nofetchwrapper can screen — the browser resolves and follows on its own. The URL is model-named, so the capability applies the policy before launching: non-http(s) schemes are always refused, and on an auth-enforced deployment (isAuthEnforced) the URL must passisSafePublicHttpsUrl. A local install allows loopback and private addresses, because screenshotting the app onlocalhostis the reason to take one there. packages/cli-workflow/src/index.ts— runs on the operator’s machine against their own API URL, loopback by default.packages/websocket/src/mcp-server.ts— thenodetool mcp serveforwarder reaches the local server’s/mcpmount and refuses any host other than127.0.0.1orlocalhost.packages/deploy/src/admin-client.ts— the server being deployed.
Scoped optional browser screenshots.
packages/server-feature-packs/src/scoped-services.ts executes
lib.browser.Screenshot only with an administrator-configured browser service.
It checks the workflow URL with assertSafePublicHttpsUrl and rejects embedded
URL credentials before navigation. The service creates a fresh isolated session
for the run owner. This check applies to the initial URL only. The browser resolves DNS and follows redirects and
subresource URLs itself, outside safeFetch. Deployment egress controls must
restrict those requests and prevent access to private addresses. The initial
HTTPS check does not provide redirect or DNS-rebinding protection.
Browser-side. The socket belongs to the viewer’s browser, not the server:
packages/game-renderer/src/standalone-assets.ts (only digest-named
./assets/ paths with allowed media extensions, redirects rejected and response
bytes verified against the binding’s SHA-256 before use),
packages/game-renderer/src/standalone-player.ts (fixed relative game document
and bundled ./assets/ paths),
packages/game-renderer/src/standalone-player3d.ts (fixed relative game.json
and manifest.json, then digest-named ./assets/ paths validated against the
closed export manifest),
packages/game-renderer/src/audio/player.ts and
packages/game-renderer/src/browser-fonts.ts (asset URLs resolved by the web
app, or bundled ./assets/ paths in a standalone export),
packages/image-nodes/src/nodes/image-io.ts (behind !IS_NODE),
packages/core-nodes/src/nodes/fake-media.ts,
packages/browser/src/capture.ts (inside page.evaluate).
The standalone 3D export applies connect-src 'self' CSP. Where redirects are
allowed, the browser follows them subject to that policy and its own network
restrictions. These fetches open no server-side socket.
Adding a surface
When a change lets a new URL reach fetch, answer these in the PR and add the
row to url-egress-inventory.ts — the audit fails without it:
- Input source. Who picks the URL: a model, a workflow, a chat client, a provider’s response, or a constant in this repo? Anything but the last is caller data.
- Egress target. Does this process open the socket, or does a browser, a subprocess, or the provider? Only the first is our SSRF.
- Authorization. What credential rides along, and would it leak on a
cross-origin redirect?
safeFetchstripsAuthorization,Cookie,Proxy-AuthorizationandX-Goog-Api-Keywhen the origin changes. - Redirects. Who checks each hop? If the answer is “the runtime follows them”, the URL had better be fixed.
- CSP. If the fetched bytes end up rendered in the web app, check
web/src/__tests__/contentSecurityPolicy.test.ts— a new media origin needs aconnect-src/img-srcentry, and stored media renders throughResponsiveImage/VideoPlayer/AudioPlayback, never a raw locator. - DNS rebinding.
deployment-egressunless the URL leaves this process for another one, in which case resolve and check.