dsh-ssrf-guard

A DeepSeek Harness function plugin holding outbound URLs to a fail-closed host and scheme allowlist, checked before a request is opened. Hosts that are not on the list never leave the box, because nothing here opens anything: the check is a URL parse and a string match.

The scope is one question: may this URL be fetched? The answer is either a small structured record or a thrown error carrying code: 'SSRF_DENIED' and a reason token. Default configuration allows nothing — you name the hosts you actually need.

What it is not

This is a URL-host allowlist. It is not DNS-rebinding protection, and it is not a WAF.

• Not DNS-rebinding protection. The hostname is matched as written in the URL, never after resolution. An allowed name whose DNS answer points at 127.0.0.1 — or that answers differently on the second lookup than on the first — is allowed by this plugin, because this plugin never looks it up. If you need that, you need a resolver-level or connect-level control, which is a different thing living in a different layer.
• Not a WAF. Nothing inspects a request body, a response, a header, or a payload. There is no rule set, no signature list, and no traffic to filter.
• Not a reverse proxy. It sits in your process as a function you call, not in front of your service as a hop.
• Not an interceptor. The pinned release candidate 0.1.1-rc.2 exposes no HTTP or fetch seam, so the plugin does not invent one and does not silently wrap your client. It gives you an assertion to call at your own egress point, and a tool the model can call before it asks for a fetch.

An allow verdict is permission to try, not a promise that the host is safe.

Install

dsh plugin --profile web add github:jwilson411/dsh-ssrf-guard

dsh plugin forwards to pnpm inside $DSH_HOME/profiles/web, then reconciles the profile: because this package's manifest declares dsh.bundle.patch, it is appended to the profile manifest's ordered dsh.profile.bundles list and its cordis.patch.yml becomes a layer. Remove it the same way, with remove in place of add.

Pinned DSH release candidate

This package is written and tested against the pinned release candidate 0.1.1-rc.2 — @deepseek-ai/dsh-tools@0.1.1-rc.2 is pinned exactly in devDependencies so tests run against one known API, and the peer range is ^0.1.1-rc.2, matching how the harness's own tool packages declare it.

Note that @deepseek-ai/dsh-tools's npm latest tag still points at the older 0.0.1-rc.1; the 0.1.1-rc.2 line is published under next. Pin explicitly rather than relying on the tag.

What it registers

Cordis plugin id	ssrf-guard (the row id in cordis.patch.yml)
Injects	tools — a hard dependency; the plugin waits rather than degrading
Tool	ssrf_check
Arguments	url (string, required)

On an allow the tool returns { ok: true, url, host, scheme, plugin }, shaped by its declared output schema. On a denial it throws rather than returning ok: false — a guard a caller can walk past by forgetting to read a boolean is not a guard.

The library API

The tool is a thin wrapper. The function is the product:

import { assertUrlAllowed, SsrfDeniedError } from 'dsh-ssrf-guard'

const config = { allowHosts: ['.example.com'], allowSchemes: ['https'] }

try {
  const { host, scheme } = assertUrlAllowed(candidate, config)
  await fetch(candidate) // your call, at your own egress point
} catch (error) {
  if (error instanceof SsrfDeniedError) {
    log.warn({ code: error.code, reason: error.reason, host: error.host })
    return
  }
  throw error
}

Call it before you build the request. A non-throwing form, checkUrl(url, config), returns { ok: false, reason, url, host, scheme, message } instead for a caller that would rather branch on a value.

Config

key	type	default
allowHosts	string[]	[]	exact hostnames and leading-dot suffix rules. Empty allows nothing.
allowSchemes	string[]	["https"]	allowed URL schemes, with or without the colon

Set them from the profile's own cordis.patch.yml — note that an id-targeted patch replaces the row's whole config, so restate every field you mean to keep:

- id: ssrf-guard
  config:
    allowHosts:
      - .example.com
      - api.vendor.test
    allowSchemes: [https]

Resolution order is patch config, then environment, then default: a patch row is the deployment's stated intent, so it is not silently overridden by an ambient variable. The environment fallbacks are DSH_SSRF_ALLOW_HOSTS and DSH_SSRF_ALLOW_SCHEMES, each a comma-separated list, and each used only when the patch row omits the key entirely. An explicitly empty list is a stated intent and wins.

How a host entry matches

entry	matches	does not match
example.com (exact)	example.com	evil.example.com, notexample.com
.example.com (suffix)	foo.example.com, a.b.example.com, example.com	notexample.com, example.com.evil.test

• Comparison is case-insensitive, since DNS is: EXAMPLE.com matches example.com.
• A trailing root dot is normalized away, so https://example.com./ cannot slip past an example.com entry as a different string.
• IPv6 brackets are normalized away, so a config may write ::1 or [::1].
• Ports are not part of the match. https://example.com:8443/ is allowed by example.com. If you need port control, that is a different layer.
• A non-string or blank entry is dropped rather than coerced: a malformed allowlist shrinks towards denying, never grows towards allowing.

What is denied by default

With no config at all, everything is. With hosts configured, the following are still denied unless you name them:

denied	reason
any host not matched by allowHosts	HOST_DENIED
any scheme outside allowSchemes — http: under the https-only default, and file:, data:, gopher:, ftp: always unless listed	SCHEME_DENIED
loopback and unspecified addresses: 127.0.0.0/8, localhost and *.localhost, ::1, 0.0.0.0, ::	LOOPBACK_DENIED
link-local, including the cloud metadata service at 169.254.169.254: 169.254.0.0/16, fe80::/10	LINK_LOCAL_DENIED
a URL carrying credentials, such as https://example.com@evil.test/	CREDENTIALS_DENIED
a relative or unparseable string	INVALID_URL
a URL that parses but carries no host, such as mailto:	HOST_MISSING

Loopback and link-local addresses are reachable only through an exact entry. A suffix rule never unlocks them: .localhost does not admit localhost, and .254 does not admit the metadata address. Naming 127.0.0.1 in allowHosts does — that case is a local development server, and it should have to be written down.

The error

error instanceof SsrfDeniedError
error.code    // 'SSRF_DENIED' — always, for every denial
error.reason  // 'HOST_DENIED' | 'SCHEME_DENIED' | 'LOOPBACK_DENIED' |
              // 'LINK_LOCAL_DENIED' | 'CREDENTIALS_DENIED' |
              // 'HOST_MISSING' | 'INVALID_URL'
error.url     // the input string, exactly as handed in
error.host    // the normalized host, or null if parsing never got that far
error.scheme  // the scheme without its colon, or null likewise
error.message // human-readable, naming what was allowed

Branch on code and reason; the message is for a human reading a log. The full reason set is exported as REASONS.

Layout

package.json          manifest + `dsh.bundle.patch` — what makes this a bundle
cordis.patch.yml      the bundle's patch layer: one insert, one plugin row
src/ssrf.js           the pure half: normalize, match, allow or throw
src/index.js          the plugin: `name`, `inject`, `apply(ctx, config)`, the tool
test/                 offline tests: URL parses, a stub context, a hygiene scan
package-lock.json     the pinned dependency tree `npm ci` installs in CI

Tests

npm install
npm test

Offline by construction, and not merely by intention: every case is a URL parse, apply is handed a stub context that records registrations, and the tool is driven through the same execute the registry calls, with results validated against the real @deepseek-ai/dsh-tools pinned to 0.1.1-rc.2. No profile boots, no name is resolved, no socket opens, and no key is read.

test/hygiene.test.js asserts the claim rather than restating it: it scans src/ for any resolver, socket, HTTP, or dynamic-import construct and fails if one appears, checks that the only non-relative import is the pinned tools package, and scans the whole tree for machine names, mount paths, and credential shapes.

CI (.github/workflows/ci.yml) runs npm ci and npm test on Node 22 and 24 from the committed lockfile, against the public registry only. It needs no credentials and the suite reaches no network.

Out of scope

• DNS-rebinding defence. Covered above: the name is checked as written, not as resolved.
• A reverse proxy or a cloud WAF. Neither is here, and this is not a smaller version of one.
• Opening sockets. The package makes no connection of any kind, including to validate that an allowed host exists.
• Scanning networks. There is no probing, no sweeping, and no discovery.
• IP-range policy beyond loopback and link-local. Private ranges such as 10.0.0.0/8 are denied by the allowlist being an allowlist, not by a special case. If you want them reachable, name them.
• Deciding for you. The tool answers about one URL. What your code does with an allow is your code's business.

License

MIT — see LICENSE.