dsh-netguard

Readme

# dsh-netguard

An egress policy for [DeepSeek Harness](https://github.com/deepseek-ai/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](https://charlotten7.github.io/dsh-netguard/)**

## 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 →](https://charlotten7.github.io/dsh-netguard/)

## Install

```sh
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:

```yaml
# $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 →](https://charlotten7.github.io/dsh-netguard/install.html)

## 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.

```yaml
- 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 →](https://charlotten7.github.io/dsh-netguard/upgrading.html)

[Configuration reference →](https://charlotten7.github.io/dsh-netguard/configuration.html) ·
[What enforcement means →](https://charlotten7.github.io/dsh-netguard/enforcement.html)

## 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 →](https://charlotten7.github.io/dsh-netguard/records.html)

## Reading it back

```sh
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`:

```sh
"$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 →](https://charlotten7.github.io/dsh-netguard/limitations.html)

## Development

```sh
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](ADR.md). Security policy is in
[SECURITY.md](SECURITY.md).

## License

MIT