dsh-netguard
An egress policy for DeepSeek Harness: a host
allowlist on the web_fetch and web_search tools, checked at connect time, and on the
destinations a bash, pwsh or run_code argument names, checked before the command runs.
Built as an out-of-repo plugin.
The harness has no network control of any kind — its sandbox governs file effects only, and
web_fetch is described in-source as an SSRF primitive with private-network protection "not
implemented". This package adds the part that is achievable from an ordinary mounted plugin.
📖 Full documentation
Three things to know before you install it
It ships in audit mode, where a denied host is recorded and reached anyway. Every decision
is recorded and every
request goes through, including the ones the policy would deny. mode: enforce is what turns
records into refusals. Audit-first is deliberate — enforce-first on a dependency graph nobody can
enumerate gets the control switched off in week one — but an installation left in audit mode has
monitoring, not enforcement.
It is not an egress firewall. Two of its three arms govern the bytes web_fetch and
web_search send. The third reads what a bash, pwsh or run_code argument says before the
child process or worker starts — so curl https://evil.example is refused and recorded, and
curl "$(cat url.txt)" is not, because it names no destination in its own text. Nothing in the
harness lets a plugin see one byte a child process sends once it has started, so a build script
phoning home does not stop, and neither does a dependency's postinstall fetching a second stage:
npm ci names no host. It does not see an MCP server's own transport either.
It is not a containment boundary. It runs in-process at the agent's own uid. Against a
confused or prompt-injected model that asks a tool to fetch a URL, or writes the URL into a
command, it is a real control. Against a model that is deliberately exfiltrating, it is advisory —
that model hides the destination behind one shell substitution. The model channel itself is the
dominant exfiltration path and nothing here touches it.
What it does not do, in full →
Install
dsh plugin --profile <name> add @deepseek-ai/dsh-headless@0.1.0-rc.6
dsh plugin --profile <name> add dsh-netguard
dsh --profile <name> --dump-config # the dsh-netguard row should appear
Any harness from 0.1.0-rc.6 through the 0.1.1 prerelease line works; 0.1.2-alpha.* does not,
because a peer range admits a prerelease only where one of its branches names that exact
major.minor.patch. CI runs the end-to-end suite against 0.1.0-rc.6, 0.1.0-rc.7, 0.1.0-rc.8
and 0.1.1-rc.2.
The composition is mandatory. ctx.web has no provider priority and no last-wins rule, so
mounting this beside another fetch provider breaks web_fetch outright with
WEB_PROVIDER_AMBIGUOUS. Write this into the profile's cordis.patch.yml — a patch replaces a
row's whole config, so every key is restated:
# $DSH_HOME/profiles/<name>/cordis.patch.yml
- id: web
config:
fetchProvider: dsh-netguard
searchProvider: deepseek-official # whatever your profile already uses
- id: tool-web
config:
fetch: true # the base bundle ships this off
searchTimeoutMs: 60000
# Only if your composition mounts the shipped provider; the base bundle does not.
# There is no `remove` patch operation — a `- remove: [...]` entry is skipped
# with a warning and leaves the provider mounted.
- id: web-fetch-http
disabled: true
- id: dsh-netguard
config:
mode: audit
allow: []
deny: []
spoolPath: /var/log/dsh/netguard.ocsf.jsonl
Get it wrong and the mount fails loud, naming the conflicting provider and quoting the patch you
need. Install from the registry or a packed tarball, not from a git spec — lib/ is a build
output git does not carry.
Install and composition in full →
Configure
Every path must be absolute; a relative one resolves against the workspace, which is the directory
the agent being recorded can rewrite. An empty allow list denies everything, and a deny match wins
over every allow match.
- id: dsh-netguard
config:
mode: audit # or enforce
allow: ['**.github.com', 'registry.npmjs.org:443']
deny: ['*.internal.example']
spoolPath: /var/log/dsh/netguard.ocsf.jsonl
shell:
enabled: true # read bash, pwsh and run_code arguments
readTextHosts: false # also read hosts written without a scheme
Pattern grammar is Codex's: *.example.com is subdomains only, **.example.com includes the
apex. An allow entry may also scope to a path — github.com/your-org/your-repo grants that path
and everything under it, re-checked on every redirect hop. A pattern that could be read two ways
is refused at load rather than widened.
A wildcard over a namespace anyone can register under is reported at load.
*.s3.amazonaws.com names a vendor and covers every bucket an attacker can create, *.slack.com
covers every Slack workspace on the internet, and *.co.ke covers every company in Kenya.
netguard compiles all three and writes a line to stderr naming the namespace, what else the entry
admits, and the Public Suffix List revision that judgement came from — because compared with no
allow list at all, *.s3.amazonaws.com is still a large narrowing and the call is the operator's.
*.mybucket.s3.amazonaws.com and the exact mybucket.s3.amazonaws.com say nothing at all.
Every request such an entry clears is recorded with the namespace on it, so
dsh-netguard report counts how much of an agent's traffic one wide entry is carrying. Name the
namespace in allowWideWildcards to record it as reviewed and stop the line; set
wideWildcards: refuse to fail the boot on it instead, which is what 0.5.0 through 0.6.0 did
unconditionally. Deny entries are unaffected.
The namespaces are the whole Public Suffix List, both sections, vendored in the package —
nothing is fetched at build or at run time — plus netguard's own table for the namespaces that
list does not carry. A namespace neither table carries is not wide as far as netguard is
concerned, and nothing warns about it.
Upgrading from 0.6.0 or earlier →
Configuration reference → ·
What enforcement means →
What it records
One OCSF Network Activity (4001) record per decision, one JSON object per line, with the
security_control profile declared. Verbatim: a validated hostname, port, resolved address,
verdict, matched rule. Digested as HMAC-SHA256: the full URL, any search query, and any string
that was supposed to be a hostname and is not.
Records carry the same correlation_uid scheme dsh-ocsf-forwarder stamps on its tool-call
records — HTTP Activity (4002) for web_fetch and web_search, not the Process Activity 1007
it gives bash — so the two together answer which tool call opened this connection. Nothing is
ever appended to the session log.
Record format and the privacy lane →
Reading it back
dsh-netguard report # everything in the spool
dsh-netguard report --since 24h
dsh-netguard report --suggest # a ready allow: block from the hosts it observed
Read --suggest output before using it. It reports what happened, not what should be permitted,
and one line in it may be the request you mounted this plugin to stop.
The CLI imports nothing from the harness, so it runs wherever the package is installed. A plugin
installed into a profile puts its bin in that profile's node_modules/.bin, which is not on
PATH:
"$DSH_HOME/profiles/<name>/node_modules/.bin/dsh-netguard" report
What the command arm reads
By default it reads one spelling: a URL written with a scheme, decided against the host and the
path, and against the refused-address table when the URL names an address literal. Every other
spelling — a bare evil.example, an scp-style git@github.com:org/repo — is off, because in a
command those tokens are usually filenames: measured on eight ordinary developer commands the
same heuristic web_search uses reads main.cc, Makefile.in, Makefile.am and socket.io as
hosts. shell.readTextHosts: true turns it on.
A command that names no destination produces no record and no refusal. A command longer than
shell.maxCommandLength (64 KiB) is refused unscanned rather than scanned inside the guard.
Known limitations
Terminals, MCP servers' own transports and delegated agents' network use are not governed, and
neither is a command that does not write its destination out. The model
channel is not governed. The spool is not rotated and the host memory is never pruned. The
wildcard tables — a documented selection from the public suffix list, plus netguard's own table of
twenty namespaces that list does not carry — are incomplete by measurement, so a self-service
namespace neither carries is still accepted. Without a search.delegate, result
URLs are not filtered — only the outbound query.
All known limitations →
Development
nvm use 22 # Node ^22.19.0 || >=24, and pnpm 11
pnpm install
pnpm run typecheck
pnpm run test
pnpm run test:coverage
pnpm run test:e2e # boots a real dsh against a mock model; no API key
Coverage is gated at 100% per file: this is a security control, so an arm nothing exercises is an
arm nobody has checked.
Design decisions and their rationale live in ADR.md. Security policy is in
SECURITY.md.
License
MIT
