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

Tool	What it does	Backend
dns_lookup	Query A / AAAA / CNAME / MX / TXT / NS / SOA / SRV / PTR / CAA records, optionally against a custom nameserver (great for testing DNS propagation)	node:dns
dns_propagation	Query one record through several public resolvers in parallel and report where they agree and where they differ — answers are grouped by record content, so "4 of 6 agree" is counted from the data; failed or slow resolvers are reported as failed rather than folded into the majority	node:dns
ping_host	ICMP ping with packet-loss and min/avg/max RTT summary	system ping
check_port	TCP connect probe: open / closed / filtered / unreachable with connect time	node:net
check_tls	Real TLS handshake; reports protocol, cipher, cert subject/issuer, validity window, days to expiry, SANs, SHA-256 fingerprint. Certificates are inspected but never trusted, so expired/self-signed certs can be diagnosed	node:tls
check_http	Fetch one HTTP(S) URL following redirects: status line, redirect chain (relative Location resolved per RFC 3986), per-phase timing (DNS / TCP connect / TLS / time to first byte / total — cumulative marks from one clock), the headers worth auditing (content-type, cache-control, HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, CORS) and how much body was read. Cookie values are counted, never echoed	node:http / node:https
trace_route	Hop-by-hop path trace with per-hop RTTs	system traceroute / tracert
my_ip	This machine's public IP, optionally with geo info (country/region/city/ISP/AS/timezone/coordinates) via ip-api.com's free keyless endpoint, with plain-IP fallback	HTTPS/HTTP GET
whois	WHOIS registry lookup over the classic TCP port 43 protocol: automatic registry discovery via the whois.iana.org referral chain (with a best-effort TLD→registry fallback map and ARIN for IP literals), raw WHOIS text plus a structured summary (registrar, statuses, created/updated/expiry dates, nameservers)	node:net raw socket

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