@aaarc/handfree-ssh-mcp 1.0.4 → 1.0.5

package/README.md

@@ -216,7 +216,8 @@ servers:
 
     # SFTP path policy — applies ONLY to upload / download / transfer.
     # execute-command is NOT affected by these lists.
-    # If `allowedRemoteDirectories` is unset or empty, SFTP is DISABLED for the server.
+    # Default is OPEN: with `allowedRemoteDirectories` unset/empty, any absolute
+    # POSIX remote path is allowed. Configure it to opt into an allowlist instead.
     allowedRemoteDirectories:
       - /home/user
       - /tmp
@@ -224,20 +225,23 @@ servers:
     # The MCP working directory is always permitted implicitly.
     allowedLocalDirectories:
       - /path/to/extra/local/dir
+    # Bypasses both the remote allowlist and the local directory check entirely.
+    # disableSftpPathPolicy: true
 ```
 
 ### 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.
+`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. Set `disableBuiltinGuards: true` and/or `disableBuiltinBlacklist: true` to turn off the built-in guards/blacklist for a server (your own `blacklist:`/`whitelist:` still apply).
 
 ### SFTP path policy
 
 | Field | Scope | Default behavior |
 |---|---|---|
-| `allowedRemoteDirectories` | `upload` / `download` / `transfer` only | **Unset = SFTP disabled.** Must list absolute POSIX directories. |
+| `allowedRemoteDirectories` | `upload` / `download` / `transfer` only | **Unset/empty = open.** Any absolute POSIX path is allowed. Configuring this list opts into restricting SFTP to those directories. |
 | `allowedLocalDirectories` | `upload` / `download` only | Unset = only the MCP working directory is allowed. |
+| `disableSftpPathPolicy` | all SFTP tools | When `true`, bypasses both checks above entirely — any remote path, any local path. |
 
-Path matching is exact-equal or `dir + separator` prefix. `..` segments and null bytes are rejected. Use `show-whitelist` to inspect a server's current SFTP policy.
+Path matching (when an allowlist is configured) is exact-equal or `dir + separator` prefix. `..` segments and null bytes are always rejected regardless of policy. Use `show-whitelist` to inspect a server's current SFTP policy.
 
 ### Jump host (ProxyJump-style)
 

package/build/config/config-loader.js

@@ -163,6 +163,9 @@ function buildYamlServerConfig(name, serverConfig, options = {}) {
     if (serverConfig.allowedLocalDirectories !== undefined) {
         merged.allowedLocalDirectories = normalizeAllowedLocalDirectories(name, serverConfig.allowedLocalDirectories);
     }
+    if (serverConfig.disableSftpPathPolicy !== undefined) {
+        merged.disableSftpPathPolicy = serverConfig.disableSftpPathPolicy === true;
+    }
     if (!allowPartial) {
         Logger.log(`Loaded server config: ${name} -> ${merged.username}@${merged.host}:${merged.port}`, "info");
     }
@@ -183,6 +186,7 @@ function mergeConfigMaps(sshConfigs, yamlConfigs) {
             commandBlacklist: yamlConfig.commandBlacklist ?? merged[name]?.commandBlacklist,
             disableBuiltinGuards: yamlConfig.disableBuiltinGuards ?? merged[name]?.disableBuiltinGuards,
             disableBuiltinBlacklist: yamlConfig.disableBuiltinBlacklist ?? merged[name]?.disableBuiltinBlacklist,
+            disableSftpPathPolicy: yamlConfig.disableSftpPathPolicy ?? merged[name]?.disableSftpPathPolicy,
             safeDirectory: yamlConfig.safeDirectory ?? merged[name]?.safeDirectory,
         };
     }

package/build/config/server.js

@@ -1,6 +1,6 @@
 export const SERVER_CONFIG = {
     name: "ssh-mcp-server",
-    version: "1.0.4",
+    version: "1.0.5",
 };
 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.
 

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

@@ -1204,14 +1204,16 @@ export class SSHConnectionManager {
      */
     validateLocalPath(localPath, name) {
         const resolvedPath = path.resolve(localPath);
+        const config = name ? this.getServerConfig(name) : undefined;
+        // disableSftpPathPolicy fully opens the local side too (any path allowed).
+        if (config?.disableSftpPathPolicy) {
+            return resolvedPath;
+        }
         const allowedRoots = new Set([process.cwd()]);
         // Add per-server allowedLocalDirectories if a server is targeted
-        if (name) {
-            const config = this.getServerConfig(name);
-            if (config?.allowedLocalDirectories) {
-                for (const dir of config.allowedLocalDirectories) {
-                    allowedRoots.add(dir);
-                }
+        if (config?.allowedLocalDirectories) {
+            for (const dir of config.allowedLocalDirectories) {
+                allowedRoots.add(dir);
             }
         }
         const isAllowed = Array.from(allowedRoots).some((root) => resolvedPath === root || resolvedPath.startsWith(root + path.sep));
@@ -1249,9 +1251,11 @@ export class SSHConnectionManager {
         const normalized = path.posix.normalize(remotePath);
         const config = this.getConfig(name);
         const allowedRoots = config.allowedRemoteDirectories ?? [];
-        if (allowedRoots.length === 0) {
-            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", `SFTP is disabled for server '${name}': no 'allowedRemoteDirectories' configured. ` +
-                `Add at least one absolute POSIX directory to 'allowedRemoteDirectories' in the YAML config to permit upload/download.`, false);
+        // Default is OPEN: with no 'allowedRemoteDirectories' configured (or
+        // disableSftpPathPolicy set), any absolute POSIX path is allowed. Configure
+        // 'allowedRemoteDirectories' to opt into an allowlist for this server.
+        if (config.disableSftpPathPolicy || allowedRoots.length === 0) {
+            return normalized;
         }
         const isAllowed = allowedRoots.some((root) => normalized === root || normalized.startsWith(root === "/" ? "/" : root + "/"));
         if (!isAllowed) {

package/build/tools/download.js

@@ -7,8 +7,8 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  */
 export function registerDownloadTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
-    server.tool("download", "Download a file from the remote server to the MCP host over SFTP. Use this when you need to inspect or save a remote file locally. The remote source must live inside one of the server's allowedRemoteDirectories; call show-whitelist to discover the allowed paths.", {
-        remotePath: z.string().describe("Path to the file on the remote server. Must be an absolute POSIX path inside one of the server's allowedRemoteDirectories (e.g. /var/log/app.log)."),
+    server.tool("download", "Download a file from the remote server to the MCP host over SFTP. Use this when you need to inspect or save a remote file locally. By default any absolute remote path is allowed; if the server configures allowedRemoteDirectories, the source must live inside one of those entries — call show-whitelist to check.", {
+        remotePath: z.string().describe("Path to the file on the remote server. Must be an absolute POSIX path (e.g. /var/log/app.log); restricted to allowedRemoteDirectories only if the server configures that list."),
         localPath: z.string().describe("Destination path on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
         connectionName: z.string().optional().describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
     }, async ({ remotePath, localPath, connectionName }) => {

package/build/tools/show-whitelist.js

@@ -100,15 +100,18 @@ export function registerShowWhitelistTool(server) {
             const allowedLocalDirs = config.allowedLocalDirectories ?? [];
             const mcpCwd = process.cwd();
             output += `## 📂 SFTP Path Policy (upload / download / transfer)\n\n`;
+            if (config.disableSftpPathPolicy) {
+                output += `**\`disableSftpPathPolicy\` is set — all path containment checks below are bypassed.** ` +
+                    `Any absolute remote path and any local path is allowed for upload/download/transfer.\n\n`;
+            }
             // ----- Remote directories -----
             output += `### Allowed remote directories\n\n`;
-            if (allowedRemoteDirs.length === 0) {
-                output += `⚠️ **\`allowedRemoteDirectories\` is NOT configured.** ` +
-                    `SFTP upload/download/transfer is **disabled** for this server — every call will be rejected with \`REMOTE_PATH_NOT_ALLOWED\`. ` +
-                    `To enable file transfer, add absolute POSIX directories under \`allowedRemoteDirectories\` in the server's YAML config.\n\n`;
+            if (config.disableSftpPathPolicy || allowedRemoteDirs.length === 0) {
+                output += `\`allowedRemoteDirectories\` is not configured, so **any absolute POSIX path is allowed** (default is open). ` +
+                    `To restrict SFTP to specific directories, add them under \`allowedRemoteDirectories\` in the server's YAML config.\n\n`;
             }
             else {
-                output += `${allowedRemoteDirs.length} entr${allowedRemoteDirs.length === 1 ? "y" : "ies"}:\n\n`;
+                output += `${allowedRemoteDirs.length} entr${allowedRemoteDirs.length === 1 ? "y" : "ies"} (restricting SFTP to these paths only):\n\n`;
                 for (const dir of allowedRemoteDirs) {
                     output += `- \`${dir}\`\n`;
                 }
@@ -116,24 +119,31 @@ export function registerShowWhitelistTool(server) {
             }
             // ----- Local directories -----
             output += `### Allowed local directories\n\n`;
-            output += `Always implicitly allowed: \`${mcpCwd}\` _(the MCP working directory)_\n\n`;
-            if (allowedLocalDirs.length === 0) {
-                output += `⚠️ **\`allowedLocalDirectories\` is NOT configured.** ` +
-                    `Only paths inside the MCP working directory above can be used as the local side of upload/download — any other path will be rejected with \`LOCAL_PATH_NOT_ALLOWED\`. ` +
-                    `To allow more locations, add absolute host paths under \`allowedLocalDirectories\` in the server's YAML config.\n\n`;
+            if (config.disableSftpPathPolicy) {
+                output += `\`disableSftpPathPolicy\` is set, so **any local path is allowed**.\n\n`;
             }
             else {
-                output += `Additional entries (${allowedLocalDirs.length}):\n\n`;
-                for (const dir of allowedLocalDirs) {
-                    output += `- \`${dir}\`\n`;
+                output += `Always implicitly allowed: \`${mcpCwd}\` _(the MCP working directory)_\n\n`;
+                if (allowedLocalDirs.length === 0) {
+                    output += `\`allowedLocalDirectories\` is not configured. ` +
+                        `Only paths inside the MCP working directory above can be used as the local side of upload/download — any other path will be rejected with \`LOCAL_PATH_NOT_ALLOWED\`. ` +
+                        `To allow more locations, add absolute host paths under \`allowedLocalDirectories\`, or set \`disableSftpPathPolicy: true\` to allow any local path.\n\n`;
+                }
+                else {
+                    output += `Additional entries (${allowedLocalDirs.length}):\n\n`;
+                    for (const dir of allowedLocalDirs) {
+                        output += `- \`${dir}\`\n`;
+                    }
+                    output += `\n`;
                 }
-                output += `\n`;
             }
             // ----- Matching rules -----
             output += `### Matching rules\n\n`;
-            output += `- A path is allowed iff it equals an entry above, or starts with \`<entry> + separator\`.\n`;
-            output += `- Remote paths must be absolute POSIX (\`/...\`); \`..\` segments and null bytes are rejected up-front.\n`;
-            output += `- Local paths are resolved on the MCP host first, then matched.\n`;
+            output += `- Default is open: with no \`allowedRemoteDirectories\` configured, any absolute POSIX remote path is allowed.\n`;
+            output += `- Configuring \`allowedRemoteDirectories\` opts into an allowlist — a path is then allowed iff it equals an entry, or starts with \`<entry> + separator\`.\n`;
+            output += `- \`disableSftpPathPolicy: true\` bypasses both the remote allowlist and the local directory check entirely.\n`;
+            output += `- Remote paths must be absolute POSIX (\`/...\`); \`..\` segments and null bytes are rejected up-front regardless of policy.\n`;
+            output += `- Local paths are resolved on the MCP host first, then matched (unless \`disableSftpPathPolicy\` is set).\n`;
             output += `- These path lists do **not** affect \`execute-command\`. They only restrict SFTP file transfers.\n\n`;
             // ----- Output log policy (execute-command full-output persistence) -----
             const outputLogRoot = sshManager.getOutputLogRoot();

package/build/tools/transfer.js

@@ -26,12 +26,12 @@ Set recursive=true when transferring a directory (upload/download only).
 For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePath.`, {
         mode: z.enum(["upload", "download", "relay"]).describe("'upload' pushes local → remote. 'download' pulls remote → local. 'relay' copies remote-A → remote-B through the MCP host."),
         localPath: z.string().optional().describe("(upload/download only) Path on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
-        remotePath: z.string().optional().describe("(upload/download only) Absolute POSIX path on the remote server. Must live inside one of the server's allowedRemoteDirectories — call show-whitelist to discover the allowed paths."),
+        remotePath: z.string().optional().describe("(upload/download only) Absolute POSIX path on the remote server. Any path is allowed by default; restricted to allowedRemoteDirectories only if the server configures that list — call show-whitelist to check."),
         connectionName: z.string().optional().describe("(upload/download only) Target server name from list-servers. Required when multiple servers are enabled."),
         sourceServer: z.string().optional().describe("(relay only) Server name to download the file from."),
-        sourceRemotePath: z.string().optional().describe("(relay only) Absolute POSIX file path on the source server. Must live inside the source server's allowedRemoteDirectories."),
+        sourceRemotePath: z.string().optional().describe("(relay only) Absolute POSIX file path on the source server. Any path is allowed by default unless the source server configures allowedRemoteDirectories."),
         destServer: z.string().optional().describe("(relay only) Server name to upload the file to."),
-        destRemotePath: z.string().optional().describe("(relay only) Absolute POSIX destination path on the target server. Must live inside the destination server's allowedRemoteDirectories."),
+        destRemotePath: z.string().optional().describe("(relay only) Absolute POSIX destination path on the target server. Any path is allowed by default unless the destination server configures allowedRemoteDirectories."),
         recursive: z.boolean().optional().describe("(upload/download only) When true, transfers an entire directory tree recursively. Default false."),
         skipIfIdentical: z.boolean().optional().describe("When true (default), skip the transfer if the destination already matches the source. " +
             "Upload: byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts (.sh / .bash / .zsh) ignore CRLF\u2194LF differences. " +

package/build/tools/upload.js

@@ -7,11 +7,11 @@ import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
  */
 export function registerUploadTool(server) {
     const sshManager = SSHConnectionManager.getInstance();
-    server.tool("upload", "Upload a local file from the MCP host to the remote server over SFTP. Use this when the file already exists locally and must be copied to the selected SSH server. The remote destination must live inside one of the server's allowedRemoteDirectories; call show-whitelist to discover the allowed paths. " +
+    server.tool("upload", "Upload a local file from the MCP host to the remote server over SFTP. Use this when the file already exists locally and must be copied to the selected SSH server. By default any absolute remote path is allowed; if the server configures allowedRemoteDirectories, the destination must live inside one of those entries — call show-whitelist to check. " +
         "Shell scripts (.sh / .bash / .zsh) with CRLF line endings are auto-converted to LF before upload (the response notes when this happens). " +
         "By default the upload is skipped if the remote file is already identical to the local one (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts are compared in a line-ending-agnostic way so CRLF\u2194LF differences alone do not trigger a re-upload) \u2014 pass skipIfIdentical=false to force a re-upload.", {
         localPath: z.string().describe("Path to a local file on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
-        remotePath: z.string().describe("Destination path on the remote server. Must be an absolute POSIX path inside one of the server's allowedRemoteDirectories (e.g. /home/user/uploads/file.txt)."),
+        remotePath: z.string().describe("Destination path on the remote server. Must be an absolute POSIX path (e.g. /home/user/uploads/file.txt); restricted to allowedRemoteDirectories only if the server configures that list."),
         connectionName: z.string().optional().describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
         skipIfIdentical: z.boolean().optional().describe("When true (default), skip the upload if the remote file is already identical (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts ignore CRLF\u2194LF differences). Set to false to force re-upload."),
     }, async ({ localPath, remotePath, connectionName, skipIfIdentical }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaarc/handfree-ssh-mcp",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
   "main": "build/index.js",
   "type": "module",