tether-tools

Remote tool invocation over the fleet bus — call laptop tools from the work node, deny-by-default.

Overview

The wintermute laptop toolkit (recall, ctrace, procstat, wchg, pevent, …) is kernel-coupled to the laptop and can't simply be re-installed on the work node. tether-tools takes the lighter path: the laptop advertises an allowlisted subset of its tools over the fleet bus (wm.fleet.tools.*) and executes invocations on behalf of the work node, returning stdout + exit code. The work node calls the tools on the machine that has them, deny-by-default and arg-sanitized.

No shell is ever invoked. All tool execution uses argv-array Command. Arg sanitization rejects shell metacharacters, disallowed flags, and path-escape sequences before any process spawn.

Acceptance Criteria

AC	Level	Description
AC1	MUST	wm-tether-tools config-example prints a valid allow.toml — parseable, absolute paths, no secrets
AC2	MUST	Manifest reply contains exactly the allowlisted tools; absent tools never appear
AC3	MUST	Invoke runs tool via argv array, returns stdout (size-capped), exit code, duration_ms
AC4	MUST	Invoke for unlisted tool rejected — error reply, zero process spawns
AC5	MUST	Arg sanitization rejects ;, |, backtick, $(, >, disallowed flags, path-escapes
AC6	MUST	Requester exits non-zero within bounded timeout with no responder — does not hang
AC7	SHOULD	End-to-end round-trip (deferred — mock test ships, embedded NATS deferred)
AC8	MUST	cargo test green; no unsafe; no sh -c; sigpipe::reset() first in main()

Install

cargo install --path .

Binary: wm-tether-tools

Usage

# Print a starter allow.toml config
wm-tether-tools config-example > ~/.config/wm-tether-tools/allow.toml

# Check responder reachability
wm-tether-tools status

# List advertised tools
wm-tether-tools list

# Invoke a remote tool
wm-tether-tools run recall -- where --limit 10

Configuration

Create ~/.config/wm-tether-tools/allow.toml:

[[tools]]
name        = "recall"
path        = "/home/jsy/.local/bin/recall"
description = "Query the wintermute memory store"
permitted_flags = ["--limit", "--since", "--format", "--json"]
permitted_args  = ["where", "what", "when", "list"]

[[tools]]
name        = "procstat"
path        = "/home/jsy/.local/bin/procstat"
description = "Snapshot process and cgroup stats as JSON"
permitted_flags = ["--json", "--pid"]
permitted_args  = []

Security model

• Deny-by-default: A tool absent from allow.toml is never advertised and never executed.
• Arg sanitization: Every argument is validated against the permitted-flags spec and a shell-metacharacter corpus before any spawn.
• No shell: Tool processes are always launched via argv array (Command::new(path).args(...)). The string sh -c does not appear in the source (grep-asserted by AC8).
• Stdout cap: Responses are capped at 64 KiB with truncated: true set when clamped.
• Timeout: Every invocation is bounded by timeout_ms (default 10s).

License

MIT OR Apache-2.0 — © Joe Yen