dsh-netdoctor

Network diagnostics toolbox for DeepSeek Harness (dsh) — nine read-only probes, zero runtime dependencies (Node.js built-ins only).

When your agent needs to answer "why can't I reach this server?", "which layer is slow?", "is the port open?", "when does this certificate expire?", "what does the public DNS actually return?" or "who owns this domain and when does it expire?" — instead of guessing or fumbling through shell commands, it can call these tools directly and read structured results.

中文简介：dsh-netdoctor 是 DeepSeek Harness 的网络诊断工具箱插件，提供 9 个只读探针（DNS 查询、多解析器 DNS 传播对比、ICMP ping、TCP 端口探测、TLS 证书检查、HTTP(S) 端点检查与分阶段计时、traceroute 路由追踪、公网 IP 与归属地查询、WHOIS 域名注册信息查询），零运行时依赖、纯 Node 内置模块实现。适合让 Agent 直接排查"连不上服务器/端口不通/证书要过期/DNS 解析异常/域名注册与到期"等常见网络问题。

Tools

Safety model

• Every tool is read-only — nothing is written, configured, or changed.
• External binaries (ping, traceroute, tracert) are invoked with fixed argument arrays, never through a shell, and every target is validated against a strict hostname/IP pattern before use.
• Every probe has a hard timeout; a hung probe can never hang a session.
• whois only opens outbound TCP port 43 connections to registry servers and sends a single query line — no credentials, no third-party API keys.
• my_ip geo lookup can be disabled per call (includeGeo: false) or in config — privacy by choice.
• check_http never authenticates: a URL with embedded credentials is rejected, cookie values are counted but never echoed back, and redirects are only followed to http/https targets.

Install

Add the plugin to your dsh configuration:

dsh plugin --profile web add github:TYEclipse/dsh-netdoctor
# or a pinned release:
dsh plugin --profile web add github:TYEclipse/dsh-netdoctor#v0.3.0

The build output (dist/) is committed to this repository, so git-hosted installs work with a single command — no build step, no approval prompts.

Or install it through the DSH web GUI plugin browser / any dsh plugin marketplace by searching dsh-netdoctor (topic dsh-plugin).

Usage

Just ask your agent — the tools appear automatically:

• "Is port 5432 open on db.internal.example.com?"
• "When does the TLS certificate for example.com expire?"
• "https://example.com/login redirects too many times — show me the chain and which layer is slow."
• "Trace the route to 1.1.1.1 and find where packets stall."
• "What A records does example.com return from 8.8.8.8?"
• "Has the new A record for example.com propagated? Check it across several public resolvers."
• "What's our public IP and where does it geolocate to?"
• "Who registered example.com and when does the domain registration expire?"
• "What CAA records does github.com publish for certificate authorities?"

Each tool returns a structured result plus a compact text summary in the conversation.

Configuration

All settings are optional; defaults are shown:

plugins:
  dsh-netdoctor:
    timeoutMs: 3000        # default timeout for TCP/TLS probes (100–60000)
    pingCount: 4           # default ICMP echo count (1–20)
    pingTimeoutSec: 2      # default per-reply wait for ping, seconds (1–60)
    maxHops: 20            # default traceroute max hops (1–64)
    traceTimeoutSec: 2     # per-hop wait for traceroute, seconds (1–30)
    includeGeo: true       # attach geo info to my_ip results
    httpTimeoutMs: 5000    # timeout for my_ip HTTP lookups (1000–60000)
    whoisTimeoutMs: 5000   # timeout for WHOIS queries over TCP port 43 (1000–60000)
    propagationTimeoutMs: 5000  # per-resolver answer deadline for dns_propagation (100–60000)

Platform notes

• Windows: ping and tracert ship with the OS — both probes work out of the box.
• macOS: ping works out of the box; traceroute is not installed by default — brew install traceroute (the tool reports a clear hint if it's missing).
• Linux: both utilities are standard (iputils / traceroute); on minimal containers ping may require iputils-ping and traceroute may require the traceroute package.
• Ping/traceroute may need elevated privileges in rare setups (e.g. restricted ICMP policies); results report failures explicitly instead of failing silently.

Develop

pnpm install
pnpm build      # tsc → dist/
pnpm test       # vitest — 107 tests, fully offline (mock DNS, local TCP/TLS/HTTP servers, parser fixtures)
pnpm lint       # oxlint src test

License

MIT © TYEclipse