Preface

When troubleshooting network issues, agents often need to answer questions such as “Why can’t I connect to the server?”, “Is the port open?”, “When does the certificate expire?”, or “What is the DNS resolution result?” If an agent directly executes ping or nslookup through a Shell, there is an injection risk, and the results are unstructured. The dsh-netdoctor plugin provides validated read-only probes that agents can call directly and read as structured results.

Plugin Overview

dsh-netdoctor is a network diagnostics toolbox for DeepSeek Harness (DSH), maintained by TYEclipse. It provides 7 read-only probes, has zero runtime dependencies, and is implemented using only Node.js built-in modules.

Core Features

The plugin includes the following 7 probes:

  • dns_lookup: Queries A/AAAA/CNAME/MX/TXT/NS/SOA/SRV/PTR/CAA records. Supports specifying custom DNS servers and can be used to test DNS propagation.
  • ping_host: Performs ICMP Ping and reports packet loss rate and minimum/average/maximum round-trip time (RTT).
  • check_port: Performs TCP connection probing and returns the port status (open/closed/filtered/unreachable) and connection duration.
  • check_tls: Performs a real TLS handshake and reports the protocol version, cipher suite, certificate subject/issuer, validity window, days until expiration, SANs, and fingerprints. The certificate is checked but the trust chain is not verified, so expired or self-signed certificates can also be diagnosed.
  • trace_route: Performs hop-by-hop path tracing and shows the RTT for each hop.
  • my_ip: Gets the local public IP. Optional geographic information can be included (country/region/city/ISP/AS/time zone/coordinates), and this feature can be disabled either at call time or in the configuration.
  • whois: Queries domain registration information via the TCP port 43 protocol. Supports automatic registry discovery and returns raw WHOIS text along with a structured summary (registrar, status, creation/update/expiration dates, name servers).

Security Model

The plugin is designed with security as a priority:

  1. Read-only operations: All probes are read-only and do not write, configure, or modify anything.
  2. Injection prevention: When calling external binaries (ping, traceroute, etc.), fixed argument arrays are used, values are never forwarded through a Shell, and strict hostname/IP pattern validation is applied to targets.
  3. Hard timeouts: Every probe has a hard timeout limit to prevent a stuck probe from hanging the entire session.
  4. No credential dependencies: whois only connects to the registry server’s TCP port 43 and sends a single-line query, without using any credentials or third-party API keys.
  5. Privacy control: The geolocation feature for my_ip is enabled by default but can be disabled through call parameters or configuration.

Installation

Add the plugin to the DSH configuration:

dsh plugin --profile web add github:TYEclipse/dsh-netdoctor

Configuration

All configuration options are optional. The defaults are as follows:

plugins:
  dsh-netdoctor:
    timeoutMs: 3000        # TCP/TLS 探测默认超时（毫秒）
    pingCount: 4           # ICMP Ping 默认发送次数
    pingTimeoutSec: 2      # Ping 每次回复等待时间（秒）
    maxHops: 20            # Traceroute 最大跳数
    traceTimeoutSec: 2     # Traceroute 每跳等待时间（秒）
    includeGeo: true       # 是否在 my_ip 结果中附加地理信息
    httpTimeoutMs: 5000    # my_ip HTTP 查询超时（毫秒）
    whoisTimeoutMs: 5000   # WHOIS 查询超时（毫秒）

Usage Examples

An agent can directly invoke the following prompts to use the tools:

  • “Is port 5432 open on db.internal.example.com?”
  • “When does the TLS certificate for example.com expire?”
  • “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?”
  • “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?”

Closing

dsh-netdoctor provides DeepSeek Harness with a safe and structured network diagnostics capability, suitable for scenarios where an agent needs to independently troubleshoot network connectivity, domain status, and certificate issues. For more details, consult the plugin directory or source repository.