dsh-top

A plugin for the DeepSeek Harness (DSH) web GUI: a system monitoring tool that shows live system stats in a floating, collapsible panel pinned to the top-right corner.

Features

• CPU — live utilisation (computed from os.cpus() tick deltas) + core count
• MEM — used / total with percentage bar (from os.totalmem() / os.freemem())
• DISK — used / total with percentage bar (platform-specific)
• NETWORK — download / upload throughput (platform-specific byte deltas)
• Top 6 processes — PID, name, CPU%, MEM% (platform-specific)
• Dark color-coded palette (cyan CPU, magenta RAM, yellow disk, blue/green network), monospace
• Draggable via the title bar, collapsible via the – / + button
• Transient monitor processes (ps, awk, head, …) are filtered out of the top-processes list

How it works

Platform support

DSH host code runs on Linux, but the DSH server can be run on any OS Node.js supports. dsh-top is multi-platform: it always reports at least CPU + memory (Node os, no subprocess), and fills in disk / network / processes where the platform allows. Missing sections are shown as n/a in the widget rather than failing the whole request.

† Windows process CPU is a lifetime-average percentage — Get-Process.CPU (cumulative CPU seconds) divided by process age, the same semantics Linux ps pcpu reports — and MEM% is derived from the real RSS bytes, not the raw working-set value. Every external collector (ps, df, powershell, …) runs with a 5 s timeout, so a wedged tool degrades its section to n/a instead of hanging the request.

* Container support is container-aware and graceful:

• Memory — when a cgroup memory limit is set (Docker --memory, a Kubernetes limit, systemd unit limit), the MEM meter reports the container's limit and current usage (cgroup v2 memory.max/memory.current, or v1 memory.limit_in_bytes/usage_in_bytes) instead of the host's total. On an unlimited cgroup it falls back to the host os.totalmem() view.
• CPU cores — when the cgroup restricts CPU (v2 cpu.max quota/period, or v1 cpu.cfs_quota_us/period_us), the core count reflects the quota; otherwise it uses os.cpus().length.
• Tightest ancestor wins, sentinels are safe — the limit files are read by walking our own cgroup path upward (not just the cgroup root), so a Docker limit under a host-level cap is reported correctly. Kernel-default sentinels are treated as "no limit": v2 max, v1 CFS -1, and the ~2^63 bytes v1 memory.limit_in_bytes reports on an unrestricted root — so an unrestricted host is never misread as having exabyte-sized RAM.
• Slim/distroless images that lack df/ps still report CPU + memory; the missing DISK/NETWORK/PROCESSES sections render as n/a.

The CPU + memory meters work on every Node platform. Disk, network and process meters depend on the listed command/pseudo-file being present — otherwise those sections render as n/a while the rest keep working.

Testing

npm test

Runs a zero-dependency suite (node --test) over the pure collector parsers with realistic fixtures: Linux (df, /proc/net/dev, ps), macOS (netstat -ib, BSD ps), and Windows (PowerShell JSON output — including the CPU-seconds→percentage and RSS-bytes→percent conversions), plus the cgroup file parsers (memory.max, cpu.max, CFS quota, and the "no limit" sentinels) and the live container memory/CPU fallback contract. The macOS/Windows parsers are verified here without needing a live Mac or Windows machine — only the thin command-execution wrapper around them is platform-bound.

Security

Because it is a system monitor, the host half reads host-wide CPU, memory, disk, network and process state. The cross-platform core (CPU + memory) uses Node's built-in os module — no subprocess and no OS-specific pseudo-files. Linux /proc reads go through Node's own fs.readFileSync. Only the platform collectors that need system tools invoke them — ps, df, and on Windows powershell — every time via execFileSync with a static argv array (never a shell string, no shell -Command interpolation of untrusted data), so there is no shell-injection surface and no attacker-controlled input. On Windows the PowerShell sub-command is a fixed script literal; none of its values come from the HTTP request. No data leaves the host, no credentials are read, and every read is read-only.

dsh.so's static scanner flags node:child_process as "critical". That is a heuristic signal on the mere presence of process access — not a vulnerability. Process access is intrinsic to a monitoring tool; review the (small) source yourself: the collectors are platform-whitelisted, argument-confined, and read-only, and any failure degrades to "n/a" rather than failing the request.

Install

dsh plugin --profile web add dsh-top

Then restart the web app and refresh the page — the panel appears at the top-right.

License

MIT