@yawlabs/ssh-mcp 0.9.2 → 0.10.0

package/README.md

@@ -66,7 +66,7 @@ Tools that fix your local SSH setup so everything else — git, deploys, tunnels
 
 | Tool | Description |
 |------|-------------|
-| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code. |
+| `ssh_exec` | Execute a command on a remote host. Returns stdout, stderr, and exit code (or `[signal: NAME]` and `code: -1` when the channel closed signal-only). Subject to [command policy](#command-policy) if configured. |
 | `ssh_read_file` | Read a file from a remote host via SFTP. |
 | `ssh_write_file` | Write content to a file on a remote host via SFTP. |
 | `ssh_upload` | Upload a local file to a remote host via SFTP. |
@@ -79,10 +79,10 @@ Tools that wrap common patterns agents build with ssh_exec — faster and less e
 
 | Tool | Description |
 |------|-------------|
-| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. |
-| `ssh_find` | Search for files remotely with structured parameters (name, type, size, depth). |
+| `ssh_multi_exec` | Run a command on multiple hosts in parallel. Returns results per host. Subject to [command policy](#command-policy) if configured (policy is checked once before fan-out). |
+| `ssh_find` | Search for files remotely with structured parameters (`name`, `type`, `size`, `depth`, `newer` — match files modified more recently than a reference path). |
 | `ssh_tail` | Read the last N lines of a file, optionally filtered by a grep pattern. |
-| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). |
+| `ssh_service_status` | Check systemd service status (active, PID, uptime, description). Flags `isError` only when the unit could not be found / queried, not when an existing unit is intentionally stopped. |
 
 ### Auto-diagnostics
 
@@ -92,6 +92,8 @@ When any remote operation fails, ssh-mcp automatically runs diagnostics and incl
 
 Remote operations reuse SSH connections automatically. When your agent makes multiple calls to the same host, the first call opens a connection and subsequent calls reuse it. Connections are kept alive for 60 seconds after the last use, then closed automatically.
 
+The pool caps at 100 active connections by default. Set `SSH_MCP_MAX_POOL_SIZE=<n>` to raise it for fan-out workloads against many distinct hosts (e.g. `ssh_multi_exec` across a large fleet). When the cap is reached, the pool evicts an idle entry to make room; if every entry is in use it rejects with `Connection pool is full`.
+
 ### SSH config support
 
 All connections respect your `~/.ssh/config`. Host aliases, custom ports, usernames, identity files, and ProxyJump settings are used automatically. If you have `Host myserver` configured in your SSH config, just pass `host: "myserver"` — ssh-mcp resolves everything.
@@ -110,6 +112,29 @@ For stricter environments, set `SSH_MCP_STRICT_HOST_KEY=1` to reject unknown hos
 
 The diagnostic tools (`ssh_test`, `ssh_diagnose`) use `StrictHostKeyChecking=no` for their probe commands. Those probes only run `echo SSH_OK` — no credentials or data pass through — so the relaxed setting is safe for connectivity testing. Real operations always go through the `hostVerifier`.
 
+### Command policy
+
+`ssh_exec` and `ssh_multi_exec` accept free-form shell commands from the agent. For security-conscious deployments, you can restrict which commands run via two env vars, each accepting a comma-separated list of regex patterns:
+
+- `SSH_MCP_COMMAND_WHITELIST` — if set, the command **must** match at least one pattern, else it's blocked.
+- `SSH_MCP_COMMAND_BLACKLIST` — if set, the command **must not** match any pattern, else it's blocked.
+
+When both are set, the command must pass both checks (whitelist first, then blacklist). When neither is set (the default), all commands are allowed.
+
+Patterns are JavaScript regexes. Use `^` and `$` for anchored matches; otherwise patterns are treated as substring matches. Commas are the delimiter, so a literal comma in a pattern needs to be expressed as `\x2c` or via a character class.
+
+```bash
+# Read-only allowlist: only ls / df / cat / find / tail
+SSH_MCP_COMMAND_WHITELIST="^ls( .*)?,^df( .*)?,^cat ,^find ,^tail "
+
+# Block destructive ops even if your agent goes off-script
+SSH_MCP_COMMAND_BLACKLIST="^rm ,^shutdown,^reboot,^mkfs,^dd if=,>\s*/dev/"
+```
+
+Blocked commands surface as a clear error mentioning which pattern (or which env var) rejected the call, so the agent can adapt rather than guess. Policy is enforced before the SSH connection opens — no remote process is started for a blocked command.
+
+The structured higher-level tools (`ssh_find`, `ssh_tail`, `ssh_service_status`, SFTP ops) are exempt from policy. They build commands from typed parameters, so a tight `^ls` whitelist would otherwise force you to allow `^find `, `^tail `, `^systemctl ` just to keep those tools working — defeating the point of a tight whitelist.
+
 ### Windows support
 
 On Windows, ssh-mcp detects the OpenSSH Authentication Agent service automatically (via the `\\.\pipe\openssh-ssh-agent` named pipe). No `SSH_AUTH_SOCK` needed — just make sure the OpenSSH agent service is running.

package/dist/index.js

@@ -343,6 +343,13 @@ function ensureAgent() {
   if (process.platform === "win32") {
     const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
     if (result) return result;
+    return {
+      running: false,
+      reachable: false,
+      keys: [],
+      started: false,
+      message: "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
+    };
   }
   const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
@@ -370,7 +377,7 @@ function ensureAgent() {
     reachable: false,
     keys: [],
     started: false,
-    message: process.platform === "win32" ? "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent" : 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
   };
 }
 function detectKeyType(filePath, fileName) {
@@ -1220,6 +1227,7 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
   const descMatch = raw.match(/^\s+.*?-\s+(.+)$/m);
   const pidMatch = raw.match(/Main PID:\s+(\d+)/);
   const sinceMatch = raw.match(/since\s+(.+?);/);
+  const unknown = !activeMatch && result.code !== 0;
   const fallbackStatus = result.code === 0 ? "active" : "inactive";
   return {
     name: serviceName,
@@ -1228,10 +1236,41 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
     description: descMatch?.[1]?.trim(),
     since: sinceMatch?.[1]?.trim(),
     pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
-    raw
+    raw,
+    unknown
   };
 }
 
+// src/policy.ts
+function parsePatterns(raw) {
+  if (!raw) return [];
+  const patterns = [];
+  for (const p of raw.split(",")) {
+    const cleaned = p.replace(/^\s+/, "");
+    if (!cleaned) continue;
+    try {
+      patterns.push(new RegExp(cleaned));
+    } catch {
+      console.error(`ssh-mcp: ignoring malformed regex in command policy: "${cleaned}"`);
+    }
+  }
+  return patterns;
+}
+function enforcePolicy(command) {
+  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST);
+  if (whitelist.length > 0 && !whitelist.some((r) => r.test(command))) {
+    throw new Error(
+      `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`
+    );
+  }
+  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST);
+  for (const pattern of blacklist) {
+    if (pattern.test(command)) {
+      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
+    }
+  }
+}
+
 // src/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
 var PortSchema = z.number().int().min(1).max(65535).optional().describe("SSH port (default: 22)");
@@ -1252,19 +1291,21 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured.",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
       timeout: TimeoutSchema
     },
     async ({ command, timeout, ...conn }) => {
+      enforcePolicy(command);
       return connectionPool.withConnection(conn, async (client) => {
         const result = await exec(client, command, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
         if (result.stderr) parts.push(`[stderr]
 ${result.stderr}`);
+        if (result.signal) parts.push(`[signal: ${result.signal}]`);
         parts.push(`[exit code: ${result.code}]`);
         return { content: [{ type: "text", text: parts.join("\n") }] };
       });
@@ -1501,7 +1542,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -1512,6 +1553,7 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      enforcePolicy(command);
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
       const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
       const lines = [];
@@ -1601,7 +1643,7 @@ ${files.join("\n")}` }] };
         if (status.since) lines.push(`Since: ${status.since}`);
         lines.push("");
         lines.push(status.raw);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
       });
     }
   );

package/dist/server.d.ts

@@ -175,11 +175,29 @@ interface ServiceStatus {
     since?: string;
     pid?: number;
     raw: string;
+    /**
+     * True when systemctl could not report on the unit at all: no `Active:` line
+     * parseable AND non-zero exit. Typical causes: typo'd unit name, unit file
+     * doesn't exist, systemd unreachable. Distinct from "service exists but is
+     * stopped" (active=false but unknown=false).
+     */
+    unknown: boolean;
 }
 declare function serviceStatus(client: Client, serviceName: string, timeoutMs?: number): Promise<ServiceStatus>;
 
+/**
+ * Check a command against the env-configured policy. Throws if blocked.
+ *
+ * Called from MCP tool handlers (ssh_exec, ssh_multi_exec) -- not from `exec()` itself,
+ * so library consumers using the programmatic API don't get policy enforcement (they're
+ * outside the MCP trust boundary and write their own gating).
+ */
+declare function enforcePolicy(command: string): void;
+/** Returns true if any policy is currently configured. Used by tool descriptions to surface that. */
+declare function isPolicyConfigured(): boolean;
+
 declare function registerTools(server: McpServer, pool?: ConnectionPool): void;
 
 declare function createServer(pool?: ConnectionPool): McpServer;
 
-export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, diagnose, downloadFile, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, listDir, listSshKeys, loadKey, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, tail, testConnection, uploadFile, writeFile };
+export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, diagnose, downloadFile, enforcePolicy, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, isPolicyConfigured, listDir, listSshKeys, loadKey, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, tail, testConnection, uploadFile, writeFile };

package/dist/server.js

@@ -339,6 +339,13 @@ function ensureAgent() {
   if (process.platform === "win32") {
     const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
     if (result) return result;
+    return {
+      running: false,
+      reachable: false,
+      keys: [],
+      started: false,
+      message: "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
+    };
   }
   const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
   if (ok) {
@@ -366,7 +373,7 @@ function ensureAgent() {
     reachable: false,
     keys: [],
     started: false,
-    message: process.platform === "win32" ? "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent" : 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
   };
 }
 function detectKeyType(filePath, fileName) {
@@ -1031,6 +1038,7 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
   const descMatch = raw.match(/^\s+.*?-\s+(.+)$/m);
   const pidMatch = raw.match(/Main PID:\s+(\d+)/);
   const sinceMatch = raw.match(/since\s+(.+?);/);
+  const unknown = !activeMatch && result.code !== 0;
   const fallbackStatus = result.code === 0 ? "active" : "inactive";
   return {
     name: serviceName,
@@ -1039,10 +1047,44 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
     description: descMatch?.[1]?.trim(),
     since: sinceMatch?.[1]?.trim(),
     pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
-    raw
+    raw,
+    unknown
   };
 }
 
+// src/policy.ts
+function parsePatterns(raw) {
+  if (!raw) return [];
+  const patterns = [];
+  for (const p of raw.split(",")) {
+    const cleaned = p.replace(/^\s+/, "");
+    if (!cleaned) continue;
+    try {
+      patterns.push(new RegExp(cleaned));
+    } catch {
+      console.error(`ssh-mcp: ignoring malformed regex in command policy: "${cleaned}"`);
+    }
+  }
+  return patterns;
+}
+function enforcePolicy(command) {
+  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST);
+  if (whitelist.length > 0 && !whitelist.some((r) => r.test(command))) {
+    throw new Error(
+      `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`
+    );
+  }
+  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST);
+  for (const pattern of blacklist) {
+    if (pattern.test(command)) {
+      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
+    }
+  }
+}
+function isPolicyConfigured() {
+  return Boolean(process.env.SSH_MCP_COMMAND_WHITELIST?.trim() || process.env.SSH_MCP_COMMAND_BLACKLIST?.trim());
+}
+
 // src/pool.ts
 function defaultMaxPoolSize() {
   const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
@@ -1257,19 +1299,21 @@ function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
     "ssh_exec",
-    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code.",
+    "Execute a command on a remote host via SSH. The command is interpreted by the remote login shell \u2014 pipes, redirects, globs, and other shell metacharacters work as expected. Returns stdout, stderr, and exit code. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured.",
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
       timeout: TimeoutSchema
     },
     async ({ command, timeout, ...conn }) => {
+      enforcePolicy(command);
       return connectionPool.withConnection(conn, async (client) => {
         const result = await exec(client, command, timeout || 3e4);
         const parts = [];
         if (result.stdout) parts.push(result.stdout);
         if (result.stderr) parts.push(`[stderr]
 ${result.stderr}`);
+        if (result.signal) parts.push(`[signal: ${result.signal}]`);
         parts.push(`[exit code: ${result.code}]`);
         return { content: [{ type: "text", text: parts.join("\n") }] };
       });
@@ -1506,7 +1550,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side.",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -1517,6 +1561,7 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
+      enforcePolicy(command);
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
       const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
       const lines = [];
@@ -1606,7 +1651,7 @@ ${files.join("\n")}` }] };
         if (status.since) lines.push(`Since: ${status.since}`);
         lines.push("");
         lines.push(status.raw);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
       });
     }
   );
@@ -1638,11 +1683,13 @@ export {
   createServer,
   diagnose,
   downloadFile,
+  enforcePolicy,
   ensureAgent,
   exec,
   find,
   fixKnownHosts,
   formatDiagnostics,
+  isPolicyConfigured,
   listDir,
   listSshKeys,
   loadKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "MCP server for SSH operations with built-in diagnostics",
   "type": "module",
   "bin": {