@aaarc/handfree-ssh-mcp 1.0.0 → 1.0.1

package/README.md

@@ -13,7 +13,7 @@ The original ssh-mcp-server requires passing credentials and options via CLI arg
 **handfree-ssh-mcp** takes a different approach:
 
 1. **Reuse your existing `~/.ssh/config`** automatically, or configure servers once in YAML
-2. **Set your security whitelists** per server through a YAML overlay
+2. **Set command policies** per server through a YAML overlay
 3. **Let the LLM call whatever it needs** - hands-free
 
 Less manual interventions. Just autonomous SSH execution with safeguards.
@@ -24,7 +24,7 @@ Less manual interventions. Just autonomous SSH execution with safeguards.
 |---------|----------|------------------|
 | Configuration | CLI args | **OpenSSH `~/.ssh/config` + optional YAML overlay** |
 | Multi-server | Messy `--ssh` flags | **Clean YAML structure** |
-| Whitelists | Single comma-separated string | **Per-server arrays** |
+| Command policy | Single comma-separated whitelist | **Blacklist mode by default, optional whitelist mode** |
 | Streaming | Not supported | **Real-time output with `stream` param** |
 | Discoverability | None | **`show-whitelist` tool for LLM** |
 
@@ -48,7 +48,7 @@ you can start the MCP without a YAML file:
   "mcpServers": {
     "ssh": {
       "command": "npx",
-      "args": ["-y", "handfree-ssh-mcp", "--enable-servers", "dev"]
+      "args": ["-y", "@aaarc/handfree-ssh-mcp", "--enable-servers", "dev"]
     }
   }
 }
@@ -65,23 +65,21 @@ servers:
   dev:  # Server name - use this in --enable-servers
     # host / port / username / privateKey can be omitted when dev exists in ~/.ssh/config.
     # Values here override the OpenSSH config entry when present.
-    whitelist:
-      - "^ls.*$"
-      - "^cat.*$"
-      - "^pwd$"
-      - "^docker.*$"
-      - "^git.*$"
-      # Add whatever commands you trust the LLM to run
-
+    # commandMode defaults to blacklist: commands are allowed unless they
+    # match the built-in dangerous blacklist or a pattern below.
+    blacklist:
+      - "^docker system prune.*$"
+
   prod:
     host: XXXXX
     port: 22
-    username: deploy
-    privateKey: ~/.ssh/id_rsa
-    whitelist:
-      - "^ls.*$"        # Read only
-      - "^cat.*$"
-      - "^tail.*$"
+    username: deploy
+    privateKey: ~/.ssh/id_rsa
+    commandMode: whitelist
+    whitelist:
+      - "^ls.*$"        # Read only
+      - "^cat.*$"
+      - "^tail.*$"
     blacklist:
       - "^rm.*$"        # Never allow delete
       - "^shutdown.*$"
@@ -116,7 +114,7 @@ The AI can now execute commands on your servers. All within your defined securit
 | Tool | Description |
 |------|-------------|
 | `execute-command` | Run SSH command (with optional `stream` for real-time output) |
-| `show-whitelist` | Show allowed commands + SFTP policy + output-log path for a server |
+| `show-whitelist` | Show active command policy + SFTP policy + output-log path for a server |
 | `upload` | Upload local file to a remote server (CRLF-fix for shell scripts, skip-if-identical) |
 | `download` | Download remote file to local disk |
 | `transfer` | Unified upload / download / server-to-server relay (`mode`: `upload` / `download` / `relay`, optional `recursive`, optional `skipIfIdentical`) |
@@ -125,7 +123,7 @@ The AI can now execute commands on your servers. All within your defined securit
 
 ### show-whitelist
 
-**Use this first!** Let the LLM know what it's allowed to do:
+**Use this first!** Let the LLM inspect the active command policy:
 
 ```json
 {
@@ -136,7 +134,7 @@ The AI can now execute commands on your servers. All within your defined securit
 }
 ```
 
-Returns a formatted list of allowed command patterns with examples.
+Returns command mode, built-in command guards, configured whitelist/blacklist patterns, and examples when whitelist mode is active.
 
 ### execute-command
 
@@ -202,12 +200,14 @@ servers:
     # Network
     socksProxy: socks5://host:port
     
-    # Security (regex patterns)
-    whitelist:                  # Only allow matching commands
-      - "^ls.*$"
-      - "^cat.*$"
-    blacklist:                  # Block matching commands
-      - "^rm -rf.*$"
+    # Command policy (regex patterns)
+    # Default is blacklist. Set commandMode: whitelist to require a whitelist.
+    commandMode: blacklist
+    whitelist:                  # Active only in whitelist mode
+      - "^ls.*$"
+      - "^cat.*$"
+    blacklist:                  # Block matching commands
+      - "^docker system prune.*$"
     
     # Safe directory for destructive commands (rm, etc.)
     safeDirectory: /home/user   # rm allowed only within this path
@@ -224,9 +224,9 @@ servers:
       - /path/to/extra/local/dir
 ```
 
-### Security note: command whitelist
-
-If a server's YAML omits `whitelist:` (or sets it to an empty list), `execute-command` falls back to a built-in default whitelist. That default covers common read-mostly tools like `git .*`, `curl .*`, `find .*`, `awk .*`, `sed .*` — broad enough that a determined LLM could write to disk via `awk 'BEGIN{system(...)}'` or similar. It is **strongly recommended to provide an explicit per-server `whitelist:`** narrowed to the commands you actually need. Startup logs a warning whenever a server is running on the default whitelist. See `show-whitelist` to inspect the effective whitelist at runtime.
+### Security note: command policy
+
+`execute-command` defaults to `commandMode: blacklist`. In that mode commands are allowed unless they match built-in destructive guards, the built-in dangerous-command blacklist, or a server's configured `blacklist:` patterns. Built-in blocked operations include hidden/chained destructive file operations, risky absolute-path output redirection, system power commands (`reboot`, `shutdown`, `halt`, `poweroff`), recursive force delete (`rm -rf`), destructive disk writes (`dd ... of=`), and filesystem formatting commands. Set `commandMode: whitelist` to require every command to match `whitelist:` after blacklist checks. For compatibility, a YAML server that contains `whitelist:` without `commandMode:` is treated as whitelist mode.
 
 ### SFTP path policy
 
@@ -302,7 +302,7 @@ Example with selective servers:
 
 ## 🛡️ Security
 
-- **Whitelist everything**: Define exactly what commands are allowed
+- **Pick the right command policy**: use default blacklist mode for flexible automation, or `commandMode: whitelist` for locked-down hosts
 - **Keep secrets safe**: Add `servers.yaml` to `.gitignore`
 - **Per-server control**: Prod can be locked down, dev can be permissive
 

package/build/config/config-loader.js

@@ -130,8 +130,15 @@ function buildYamlServerConfig(name, serverConfig, options = {}) {
     }
     if (serverConfig.socksProxy !== undefined)
         merged.socksProxy = serverConfig.socksProxy ?? undefined;
+    if (serverConfig.commandMode !== undefined) {
+        if (serverConfig.commandMode !== "blacklist" && serverConfig.commandMode !== "whitelist") {
+            throw new Error(`Server '${name}': 'commandMode' must be 'blacklist' or 'whitelist'`);
+        }
+        merged.commandMode = serverConfig.commandMode;
+    }
     if (serverConfig.whitelist !== undefined) {
         merged.commandWhitelist = serverConfig.whitelist ?? undefined;
+        merged.commandMode ??= "whitelist";
     }
     if (serverConfig.blacklist !== undefined) {
         merged.commandBlacklist = serverConfig.blacklist ?? undefined;
@@ -159,6 +166,7 @@ function mergeConfigMaps(sshConfigs, yamlConfigs) {
             name,
             allowedRemoteDirectories: yamlConfig.allowedRemoteDirectories ?? merged[name]?.allowedRemoteDirectories,
             allowedLocalDirectories: yamlConfig.allowedLocalDirectories ?? merged[name]?.allowedLocalDirectories,
+            commandMode: yamlConfig.commandMode ?? merged[name]?.commandMode,
             commandWhitelist: yamlConfig.commandWhitelist ?? merged[name]?.commandWhitelist,
             commandBlacklist: yamlConfig.commandBlacklist ?? merged[name]?.commandBlacklist,
             safeDirectory: yamlConfig.safeDirectory ?? merged[name]?.safeDirectory,

package/build/config/server.js

@@ -1,13 +1,13 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.4.0",
+    version: "1.0.1",
 };
 export const SERVER_INSTRUCTIONS = `This server provides SSH access to servers loaded from OpenSSH config (~/.ssh/config by default) and optional YAML config/policy overlays.
 
 Recommended workflow:
 1. Call list-servers first to discover which server names are available, enabled, and currently connected.
-2. Use show-whitelist before execute-command when you are unsure whether a command is allowed.
-3. Use execute-command for remote shell commands. Prefer a single command per call. Compound commands such as "cmd1 && cmd2" may be rejected by whitelist rules even if each subcommand is individually safe.
+2. Use show-whitelist before execute-command when you are unsure which command policy is active.
+3. Use execute-command for remote shell commands. Prefer a single command per call. Compound commands may be rejected by command policy even if each subcommand is individually safe.
 4. Use stream=false for short commands that should finish quickly, such as pwd, ls, cat, head, tail, git status, or docker ps.
 5. Use stream=true for commands that may take longer or where incremental output is useful.
 6. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
@@ -19,7 +19,7 @@ Server targeting:
 
 Behavior notes:
 - A tool may automatically establish the SSH connection on first use.
-- Command execution is restricted by the configured whitelist and blacklist. If a command is rejected, inspect the whitelist rather than retrying the same command repeatedly.
+- Command execution uses blacklist mode by default, with a built-in dangerous-command blacklist. Servers can opt into whitelist mode through YAML. If a command is rejected, inspect the command policy rather than retrying the same command repeatedly.
 - Some commands return no output on success; this is normal.
 - File transfer tools use SFTP and can fail if the remote path is missing or permissions are insufficient.
 - OpenSSH/YAML config changes are hot-reloaded without restarting the server. Connection-field changes close the old client so the next tool call reconnects with fresh settings.`;

package/build/core/mcp-server.js

@@ -148,11 +148,6 @@ export class SshMcpServer {
         const parsedArgs = this.loadConfig();
         this.sshManager.setConfig(parsedArgs.configs, parsedArgs.enabledServers);
         this.sshManager.setOutputLogRoot(parsedArgs.outputLogDir);
-        // Security warning
-        const allConfigs = Object.values(parsedArgs.configs);
-        if (allConfigs.some((c) => !c.commandWhitelist || c.commandWhitelist.length === 0)) {
-            Logger.log("WARNING: Running without a command whitelist is strongly discouraged. Please configure a whitelist to restrict the commands that can be executed.", "info");
-        }
         // Pre-connect to enabled servers if flag is set
         if (parsedArgs.preConnect) {
             Logger.log("Pre-connecting to enabled SSH servers...", "info");

package/build/services/ssh-connection-manager.js

@@ -20,78 +20,33 @@ const CONNECTION_RESET_FIELDS = [
     "authOptional",
     "socksProxy",
 ];
-/**
- * Default command whitelist - only allow safe Linux commands
- * These patterns are regex strings that match allowed commands
- */
-/**
- * Default command whitelist - only allow safe Linux commands
- * These patterns are regex strings that match allowed commands
- *
- * SECURITY: Commands not matching any pattern will be BLOCKED with an error message
- */
-const DEFAULT_COMMAND_WHITELIST = [
-    // Basic file operations (READ-ONLY)
-    "^ls( .*)?$",
-    "^cat .*$",
-    "^head .*$",
-    "^tail .*$",
-    "^less .*$",
-    "^more .*$",
-    "^wc .*$",
-    "^file .*$",
-    "^stat .*$",
-    "^find .*$",
-    "^grep .*$",
-    "^awk .*$",
-    "^sed .*$",
-    // Directory navigation
-    "^pwd$",
-    "^cd .*$",
-    // System info (read-only)
-    "^echo .*$",
-    "^hostname$",
-    "^whoami$",
-    "^id$",
-    "^uname .*$",
-    "^df .*$",
-    "^du .*$",
-    "^free .*$",
-    "^top -bn1.*$",
-    "^ps .*$",
-    "^uptime$",
-    "^date$",
-    "^env$",
-    "^printenv.*$",
-    // Network diagnostics (read-only)
-    "^ping -c \\d+ .*$",
-    "^curl .*$",
-    "^wget .*$",
-    "^netstat .*$",
-    "^ss .*$",
-    "^ip .*$",
-    // Git operations
-    "^git .*$",
-    // Systemctl (read-only)
-    "^systemctl status .*$",
-    "^systemctl list-.*$",
-    "^journalctl .*$",
-    // Docker (read-only)
-    "^docker ps.*$",
-    "^docker logs.*$",
-    "^docker images.*$",
-    "^docker inspect.*$",
-    // ============================================
-    // DANGEROUS COMMANDS - EXPLICITLY BANNED:
-    // - rm, rmdir (delete files/dirs)
-    // - mv (can overwrite/move files)
-    // - cp (can overwrite files)
-    // - chmod, chown (change permissions)
-    // - kill, pkill (terminate processes)
-    // - mkdir, touch (create files/dirs)
-    // - >, >> (redirect/overwrite files)
-    // - wget -O, curl -o (download and overwrite)
-    // ============================================
+export const BUILT_IN_COMMAND_BLACKLIST = [
+    { regex: /^\s*(?:sudo\s+)?(?:reboot|shutdown|halt|poweroff)(?:\s|$)/i, reason: "system power command" },
+    { regex: /\b(?:Restart-Computer|Stop-Computer)\b/i, reason: "Windows power command" },
+    { regex: /^\s*(?:sudo\s+)?(?:init\s+[06]|telinit\s+[06])(?:\s|$)/i, reason: "system runlevel power command" },
+    { regex: /^\s*(?:sudo\s+)?rm\b(?=.*(?:\s--recursive\b|\s-\S*r))(?=.*(?:\s--force\b|\s-\S*f))/i, reason: "recursive force rm" },
+    { regex: /\bRemove-Item\b(?=.*\s-Recurse(?:\s|$))(?=.*\s-Force(?:\s|$))/i, reason: "recursive force Remove-Item" },
+    { regex: /^\s*(?:del|erase|rd)\b(?=.*(?:\/s\b|\s-Recurse(?:\s|$)))(?=.*(?:\/q\b|\s-Force(?:\s|$)))/i, reason: "recursive quiet Windows delete" },
+    { regex: /^\s*(?:sudo\s+)?rmdir\s+(?:\/|\*|~|\$HOME|%USERPROFILE%|[A-Za-z]:\\)(?:\s|$)/i, reason: "dangerous rmdir target" },
+    { regex: /^\s*(?:sudo\s+)?dd\b.*\bof=/i, reason: "dd with of= (can overwrite devices/files)" },
+    { regex: /^\s*(?:sudo\s+)?mkfs(?:\.\S+)?\b/i, reason: "filesystem formatting command" },
+    { regex: /^\s*(?:sudo\s+)?(?:diskpart|format)(?:\s|$)/i, reason: "disk formatting command" },
+    { regex: /\b(?:Format-Volume|Clear-Disk|Remove-Partition)\b/i, reason: "Windows disk destructive command" },
+    { regex: /^\s*(?:sudo\s+)?chmod\s+-R\s+777\b/i, reason: "recursive world-writable chmod" },
+    { regex: /^\s*(?:sudo\s+)?chown\s+-R\s+\S+\s+\/(?:\s|$)/i, reason: "recursive chown on root" },
+];
+export const BUILT_IN_DESTRUCTIVE_GUARDS = [
+    { regex: /\brm\b/, reason: "rm in command chain" },
+    { regex: /\brmdir\b/, reason: "rmdir in command chain" },
+    { regex: /\bunlink\b/, reason: "unlink in command chain" },
+    { regex: /\bshred\b/, reason: "shred in command chain" },
+    { regex: /\btruncate\b/, reason: "truncate in command chain" },
+    { regex: /-delete\b/, reason: "find -delete detected" },
+    { regex: /-exec\s+rm\b/, reason: "find -exec rm detected" },
+    { regex: /\bmv\b/, reason: "mv detected (can overwrite)" },
+    { regex: /\bcp\b.*-f/, reason: "cp -f detected (force overwrite)" },
+    { regex: /(?<![0-9])>\s*\/(?!dev\/null)/, reason: "output redirection to absolute path" },
+    { regex: />\s*~/, reason: "output redirection to home path" },
 ];
 /**
  * SSH Connection Manager class
@@ -183,52 +138,6 @@ export class SSHConnectionManager {
     getOutputLogRoot() {
         return this.outputLogRoot ?? path.join(process.cwd(), ".handfree-output");
     }
-    /**
-     * Hot-reload mutable policy fields from a fresh config map.
-     * Only updates whitelist, blacklist, safeDirectory, allowedRemoteDirectories,
-     * and allowedLocalDirectories for servers that already exist. Does NOT touch
-     * SSH connections or credentials.
-     */
-    updatePolicies(freshConfigs) {
-        let changed = 0;
-        for (const [name, existing] of Object.entries(this.configs)) {
-            const fresh = freshConfigs[name];
-            if (!fresh)
-                continue;
-            const wlChanged = JSON.stringify(existing.commandWhitelist) !==
-                JSON.stringify(fresh.commandWhitelist);
-            const blChanged = JSON.stringify(existing.commandBlacklist) !==
-                JSON.stringify(fresh.commandBlacklist);
-            const sdChanged = existing.safeDirectory !== fresh.safeDirectory;
-            const ardChanged = JSON.stringify(existing.allowedRemoteDirectories) !==
-                JSON.stringify(fresh.allowedRemoteDirectories);
-            const aldChanged = JSON.stringify(existing.allowedLocalDirectories) !==
-                JSON.stringify(fresh.allowedLocalDirectories);
-            if (wlChanged || blChanged || sdChanged || ardChanged || aldChanged) {
-                existing.commandWhitelist = fresh.commandWhitelist;
-                existing.commandBlacklist = fresh.commandBlacklist;
-                existing.safeDirectory = fresh.safeDirectory;
-                existing.allowedRemoteDirectories = fresh.allowedRemoteDirectories;
-                existing.allowedLocalDirectories = fresh.allowedLocalDirectories;
-                changed++;
-                const parts = [];
-                if (wlChanged)
-                    parts.push(`whitelist(${(fresh.commandWhitelist ?? []).length})`);
-                if (blChanged)
-                    parts.push(`blacklist(${(fresh.commandBlacklist ?? []).length})`);
-                if (sdChanged)
-                    parts.push(`safeDirectory(${fresh.safeDirectory ?? "none"})`);
-                if (ardChanged)
-                    parts.push(`allowedRemoteDirectories(${(fresh.allowedRemoteDirectories ?? []).length})`);
-                if (aldChanged)
-                    parts.push(`allowedLocalDirectories(${(fresh.allowedLocalDirectories ?? []).length})`);
-                Logger.log(`Hot-reloaded policies for [${name}]: ${parts.join(", ")}`, "info");
-            }
-        }
-        if (changed === 0) {
-            Logger.log("Config file changed but no policy updates detected", "info");
-        }
-    }
     connectionFieldsChanged(oldConfig, nextConfig) {
         return CONNECTION_RESET_FIELDS.some((key) => oldConfig[key] !== nextConfig[key]);
     }
@@ -604,23 +513,7 @@ export class SSHConnectionManager {
      */
     getDestructiveMatch(command) {
         // This catches: "cd /; rm -rf *", "echo test && rm file", "$(rm file)", and risky writes like "> /etc/..."
-        const destructivePatterns = [
-            { regex: /\brm\b/, reason: "rm in command chain" },
-            { regex: /\brmdir\b/, reason: "rmdir in command chain" },
-            { regex: /\bunlink\b/, reason: "unlink in command chain" },
-            { regex: /\bshred\b/, reason: "shred in command chain" },
-            { regex: /\btruncate\b/, reason: "truncate in command chain" },
-            { regex: /-delete\b/, reason: "find -delete detected" },
-            { regex: /-exec\s+rm\b/, reason: "find -exec rm detected" },
-            { regex: /\bdd\b.*\bof=/, reason: "dd with of= (can overwrite files)" },
-            { regex: /\bmv\b/, reason: "mv detected (can overwrite)" },
-            { regex: /\bcp\b.*-f/, reason: "cp -f detected (force overwrite)" },
-            // Allow stderr redirection to /dev/null (2>/dev/null, 2>&1>/dev/null, etc.)
-            // Block dangerous writes like: echo x > /etc/passwd, cat > /bin/bash
-            { regex: /(?<![0-9])>\s*\/(?!dev\/null)/, reason: "output redirection to absolute path" },
-            { regex: />\s*~/, reason: "output redirection to home path" },
-        ];
-        for (const { regex, reason } of destructivePatterns) {
+        for (const { regex, reason } of BUILT_IN_DESTRUCTIVE_GUARDS) {
             if (regex.test(command)) {
                 return reason;
             }
@@ -742,32 +635,19 @@ export class SSHConnectionManager {
             }
         }
         // ========================================
-        // LAYER 2: Whitelist check for non-destructive commands
+        // LAYER 2: Built-in blacklist for high-risk operations
         // ========================================
-        // Use config whitelist if provided, otherwise use default whitelist
-        const whitelist = (config.commandWhitelist && config.commandWhitelist.length > 0)
-            ? config.commandWhitelist
-            : DEFAULT_COMMAND_WHITELIST;
-        // Check whitelist - command must match one of the patterns to be allowed
-        const matchesWhitelist = whitelist.some((pattern) => {
-            try {
-                const regex = new RegExp(pattern);
-                return regex.test(command);
-            }
-            catch (e) {
-                Logger.log(`Invalid whitelist regex pattern: ${pattern}`, "error");
-                return false;
+        for (const { regex, reason } of BUILT_IN_COMMAND_BLACKLIST) {
+            if (regex.test(command)) {
+                Logger.log(`Command blocked by built-in blacklist (${reason}): ${command}`, "info");
+                return {
+                    isAllowed: false,
+                    reason: `Command blocked by built-in blacklist: ${reason}`,
+                };
             }
-        });
-        if (!matchesWhitelist) {
-            Logger.log(`Command blocked by whitelist: ${command}`, "info");
-            return {
-                isAllowed: false,
-                reason: `Command not in whitelist, execution forbidden. Command: "${command}"`,
-            };
         }
         // ========================================
-        // LAYER 3: Blacklist check
+        // LAYER 3: User blacklist check
         // ========================================
         if (config.commandBlacklist && config.commandBlacklist.length > 0) {
             const matchesBlacklist = config.commandBlacklist.some((pattern) => {
@@ -788,6 +668,31 @@ export class SSHConnectionManager {
                 };
             }
         }
+        // ========================================
+        // LAYER 4: Optional whitelist mode
+        // ========================================
+        const commandMode = config.commandMode
+            ?? ((config.commandWhitelist && config.commandWhitelist.length > 0) ? "whitelist" : "blacklist");
+        if (commandMode === "whitelist") {
+            const whitelist = config.commandWhitelist ?? [];
+            const matchesWhitelist = whitelist.some((pattern) => {
+                try {
+                    const regex = new RegExp(pattern);
+                    return regex.test(command);
+                }
+                catch (e) {
+                    Logger.log(`Invalid whitelist regex pattern: ${pattern}`, "error");
+                    return false;
+                }
+            });
+            if (!matchesWhitelist) {
+                Logger.log(`Command blocked by whitelist: ${command}`, "info");
+                return {
+                    isAllowed: false,
+                    reason: `Command not in whitelist, execution forbidden. Command: "${command}"`,
+                };
+            }
+        }
         // Validation passed
         return {
             isAllowed: true,
@@ -914,7 +819,7 @@ export class SSHConnectionManager {
      * Execute SSH command with auto-retry on connection errors
      *
      * Features:
-     * - Validates command against whitelist/blacklist before execution
+     * - Validates command against command policy before execution
      * - Auto-reconnects and retries on connection failures
      * - Exponential backoff between retries (500ms, 1000ms, 2000ms)
      * - Configurable timeout per command
@@ -993,7 +898,7 @@ export class SSHConnectionManager {
      * Execute SSH command with real-time streaming output via progress callback
      *
      * Features:
-     * - Validates command against whitelist/blacklist before execution
+     * - Validates command against command policy before execution
      * - Streams stdout/stderr chunks to the onProgress callback in real-time
      * - Auto-reconnects and retries on connection failures
      * - Longer default timeout suitable for long-running tasks

package/build/tools/execute-command.js

@@ -12,7 +12,7 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
 export function registerExecuteCommandTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
     server.tool("execute-command", "Execute a shell command on a remote server over SSH. Use this for command-line actions on the selected host. Streaming mode is enabled by default so long-running commands can emit progress; set stream=false for short commands where you only want the final output. The returned text is tail-only-capped at maxOutputBytes PER STREAM (default 65536 bytes for stdout and 65536 bytes for stderr, so the response can be up to ~2x that); the FULL stdout/stderr is always persisted to a local log file under <cwd>/.handfree-output/<server>/<user>/, and the response includes that path whenever output was truncated.", {
-        cmdString: z.string().describe("Exact remote shell command to run. Prefer a single command per call, for example 'pwd', 'ls -la', 'cat /etc/hostname', or 'git status'. Compound commands may be blocked by whitelist rules even if each subcommand is safe."),
+        cmdString: z.string().describe("Exact remote shell command to run. Prefer a single command per call, for example 'pwd', 'ls -la', 'cat /etc/hostname', or 'git status'. Compound commands may be blocked by command policy even if each subcommand is safe."),
         connectionName: z
             .string()
             .optional()

package/build/tools/help.js

@@ -31,7 +31,7 @@ Examples:
   execute-command { cmdString: "pwd" }
   execute-command { cmdString: "docker ps -a", connectionName: "prod", stream: false }
   execute-command { cmdString: "tail -f /var/log/syslog", stream: true, timeout: 600000 }`,
-    "show-whitelist": `show-whitelist — Show allowed/blocked command patterns for a server.
+    "show-whitelist": `show-whitelist — Show the active command policy for a server.
 
 Parameters:
   connectionName  (string, see below)  Target server name from list-servers.
@@ -40,7 +40,7 @@ connectionName rule:
   • If only one server is enabled → optional (auto-selected).
   • If multiple servers are enabled → REQUIRED.
 
-Returns: Whitelist patterns, blacklist patterns, and example commands.`,
+Returns: Command mode, built-in blacklist, configured whitelist/blacklist patterns, and example commands when whitelist mode is active.`,
     "upload": `upload — Upload a single local file to a remote server over SFTP.
 
 Parameters:
@@ -115,7 +115,7 @@ const TOOL_OVERVIEW = `Available tools (use help { tool: "<name>" } for details)
 
   list-servers      Discover available SSH servers and their status.
   execute-command   Run a shell command on a remote server.
-  show-whitelist    Show allowed/blocked command patterns.
+  show-whitelist    Show the active command policy.
   upload            Upload a single file to a remote server.
   download          Download a single file from a remote server.
   transfer          Move files: single, recursive, or cross-server relay.
@@ -123,7 +123,7 @@ const TOOL_OVERVIEW = `Available tools (use help { tool: "<name>" } for details)
 
 Quick start:
   1. list-servers → discover server names
-  2. show-whitelist { connectionName: "<name>" } → see what's allowed
+  2. show-whitelist { connectionName: "<name>" } → inspect command policy
   3. execute-command { cmdString: "pwd", connectionName: "<name>" }`;
 /**
  * Register help tool