@jadchene/mcp-ssh-service 1.1.1 → 1.3.0

package/README.md

@@ -1,95 +1,267 @@
-# SSH MCP Service
-
-A production-ready, highly secure Model Context Protocol (MCP) server for remote server management. It features stateless connections, lazy loading, and a mandatory two-step confirmation flow for high-risk operations.
-
-## Core Features
-
-- **Stateless & Lazy Loading**: Connections are only established when a tool is called and closed immediately after execution. No persistent SSH tunnels.
-- **Security First**: 
-  - Mandatory manual confirmation for all "Write Actions" (e.g., `rm`, `restart`, `docker_stop`).
-  - Command blacklist (prevents `rm -rf /`, etc.).
-  - Restricted directory protection for safe deletions.
-- **Context Aware**: Supports directory aliases and path mapping via `list_working_directories`.
-- **Workflow Automation**: `execute_batch` allows running multiple commands in a single session with state (like `cd`) preserved between steps.
-
-## Tool List (45 Total)
-
-### 🛠️ Discovery & Core (8)
-- `list_servers`: List all configured SSH servers.
-- `ping_server`: Test connectivity to a specific server.
-- `list_working_directories`: View path mappings/aliases.
-- `check_dependencies`: Verify if required binaries (git, docker, etc.) are installed.
-- `get_system_info`: Get CPU, memory, and kernel details.
-- `pwd`: Show current remote path.
-- `cd`: Change directory (effective within `execute_batch`).
-- `execute_batch`: Run a sequence of tools in one session.
-
-### 💻 Shell & Basic (2)
-- `execute_command` (*): Run any arbitrary shell command.
-- `echo`: Print text or variables.
-
-### 📂 File Management (5)
-- `upload_file` (*): Transfer file from local to remote.
-- `download_file`: Transfer file from remote to local.
-- `ll`: Detailed directory listing.
-- `cat`: Read file content.
-- `edit_text_file` (*): Replace file content (Safe Base64 transfer).
-- `touch`: Create empty file or update timestamp.
-- `find`: Search for files in a directory hierarchy.
-
-### 🐳 Docker & Compose (18)
-- `docker_compose_up` (*), `docker_compose_down` (*), `docker_compose_stop` (*), `docker_compose_restart` (*)
-- `docker_compose_logs`: View compose logs.
-- `docker_ps`, `docker_images`
-- `docker_pull` (*), `docker_cp` (*), `docker_stop` (*), `docker_rm` (*), `docker_start` (*), `docker_rmi` (*), `docker_commit` (*)
-- `docker_logs`: Get container logs.
-- `docker_load` (*), `docker_save` (*)
-
-### ⚙️ System Services (4)
-- `systemctl_status`
-- `systemctl_start` (*), `systemctl_stop` (*), `systemctl_restart` (*)
-
-### 🌐 Network & Stats (8)
-- `ip_addr`: Show network interfaces.
-- `firewall_cmd` (*): Manage firewall rules.
-- `netstat`: Monitor ports and connections.
-- `nvidia_smi`: GPU status.
-- `ps`: Process snapshot.
-- `df_h`: Disk usage.
-- `du_sh`: Directory size estimation.
-
-> (*) Requires manual confirmation.
-
-## Confirmation Protocol
-
-For any tool marked with `(*)`, the service follows a two-step flow:
-1. **Request**: Call the tool with parameters. The server returns a `confirmationId` and `status: "pending"`.
-2. **Confirm**: Call the **same tool again** with `confirmExecution: true` and the provided `confirmationId`.
-
-## Configuration
-
-External configuration `config.json` allows defining multiple servers and their working directory aliases:
+English | [简体中文](./README_zh.md)
+
+# 🚀 mcp-ssh
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![MCP Ready](https://img.shields.io/badge/MCP-Ready-blue)](https://modelcontextprotocol.io/)
+
+A **production-grade** Model Context Protocol (MCP) server designed for secure, stateless SSH automation. This service empowers AI agents to manage remote infrastructure with **human-in-the-loop** safety and **semantic environment awareness**.
+
+---
+
+## 🌟 Key Pillars
+
+### 🔒 Uncompromising Security
+*   **Two-Step Confirmation**: High-risk operations (writes, deletes, restarts) return a `confirmationId`. Nothing happens until a human approves the specific transaction.
+*   **Command Blacklist**: Real-time regex interception for catastrophic commands like `rm -rf /` or `mkfs`.
+*   **Command Whitelist**: Trusted final command strings can bypass manual confirmation by matching configured regex patterns. This applies to built-in high-risk tools and to `execute_batch` sub-commands.
+*   **Single-Command Enforcement**: `execute_command` rejects shell chaining, pipes, redirection, subshells, and multiline payloads at the server layer.
+*   **Server-Level Read-Only**: Lock specific servers to a non-destructive mode at the configuration level.
+*   **Restricted File Deletion**: Hardcoded prevention of accidental deletion of system-critical paths like `/etc` or `/usr`.
+
+### 🧠 AI-Native Design
+*   **Semantic Infrastructure Discovery**: AI can list servers and understand their purposes via natural language descriptions.
+*   **Working Directory Aliases**: Map complex paths to simple aliases like `app-root` with descriptive metadata.
+*   **Contextual Pre-checks**: Built-in tools to verify dependencies (Docker, Git) before execution.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install globally via npm
+npm install -g @jadchene/mcp-ssh-service
+
+# Start the server with a config file
+mcp-ssh-service --config ./config.json
+```
+
+### Source Setup
+
+```bash
+git clone https://github.com/jadchene/mcp-ssh.git
+cd mcp-ssh
+npm install
+npm run build
+node dist/index.js --config ./config.json
+```
+
+---
+
+## 🧩 Skill Integration (Recommended)
+
+For AI assistants (Codex / Gemini / similar agents), this repository includes an SSH MCP skill that significantly improves execution quality and safety consistency.
+
+- Skill path: `skills/ssh-mcp/SKILL.md`
+- Benefits:
+  - Enforces strict two-step confirmation for high-risk operations
+  - Prefers `execute_batch` for multi-step workflows and avoids risky command chaining
+  - Standardizes server discovery, dependency checks, and post-action verification
+  - Reduces accidental destructive operations and context-loss mistakes
+
+When your agent supports skills, load this skill before using SSH MCP tools for best results.
+
+---
+
+## ⚙️ Configuration Schema
+
+### Global Settings
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `logDir` | string | Directory for logs. Supports env vars like `${HOME}`. |
+| `commandBlacklist` | string[] | Prohibited command regex patterns (e.g., `["^rm -rf"]`). |
+| `commandWhitelist` | string[] | Trusted final-command regex patterns that can skip confirmation for high-risk tools and `execute_batch` sub-commands. |
+| `defaultTimeout` | number | Command timeout in milliseconds (default: 60000). |
+| `servers` | object | Dictionary of server configs where key is the `serverAlias`. |
+
+### Server Object
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | string | Remote IP or hostname. Supports env vars. |
+| `port` | number | SSH port (default: 22). |
+| `username` | string | SSH login user. |
+| `password` | string | SSH password. Use `${VAR}` for security. |
+| `privateKeyPath` | string | Path to private key file. |
+| `passphrase` | string | Passphrase for the private key. |
+| `readOnly` | boolean | Disables all write/modify tools for this server. |
+| `desc` | string | Server description shown in `list_servers`. |
+| `strictHostKeyChecking` | boolean | Set to `false` to bypass host key verification. |
+| `workingDirectories` | object | Semantic path mappings (Key: { path, desc }). |
+| `proxyJump` | object | Optional jump host (recursive server config). |
+
+---
+
+## ⚙️ Configuration Example
 
 ```json
 {
+  "logDir": "./logs",
+  "defaultTimeout": 60000,
+  "commandBlacklist": ["^apt-get upgrade", "curl.*\\|.*sh"],
+  "commandWhitelist": ["^systemctl status\\s+nginx$", "^docker ps$"],
   "servers": {
-    "prod-web": {
-      "host": "192.168.1.100",
-      "user": "root",
-      "keyPath": "~/.ssh/id_rsa",
-      "workingDirectories": {
-        "app": { "path": "/var/www/html", "desc": "Web Root" },
-        "logs": { "path": "/var/log/nginx", "desc": "Nginx Logs" }
-      }
+    "prod-web": {
+      "desc": "Primary API Cluster",
+      "host": "10.0.0.5",
+      "username": "deploy",
+      "privateKeyPath": "~/.ssh/id_rsa",
+      "passphrase": "${SSH_KEY_PWD}",
+      "workingDirectories": {
+        "logs": { "path": "/var/log/nginx", "desc": "Nginx access logs" }
+      },
+      "proxyJump": {
+        "host": "bastion.example.com",
+        "username": "jumpuser"
+      }
+    }
+  }
+}
+```
+
+---
+
+## MCP Client Configuration
+
+The following examples show how to register this MCP server in common AI clients. Replace the config path with your own local file path. To keep the setup portable, the examples below intentionally avoid absolute paths.
+
+### Codex
+
+`~/.codex/config.toml`
+
+```toml
+[mcp_servers.ssh]
+command = "mcp-ssh-service"
+args = ["--config", "./config.json"]
+```
+
+### Gemini CLI
+
+`~/.gemini/settings.json`
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "type": "stdio",
+      "command": "mcp-ssh-service",
+      "args": [
+        "--config",
+        "./config.json"
+      ]
     }
   }
 }
 ```
 
-## Installation
+### Claude Code
 
-```bash
-npm install
-npm run build
-node dist/index.js
-```
+`~/.claude.json`
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "type": "stdio",
+      "command": "mcp-ssh-service",
+      "args": [
+        "--config",
+        "./config.json"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Integrated Toolset (50 Tools)
+
+### Discovery & Core (8)
+* `list_servers`
+* `ping_server`
+* `list_working_directories`
+* `check_dependencies`
+* `get_system_info`
+* `pwd`
+* `cd`
+* `execute_batch` [Auth Required if any sub-command is high-risk]
+
+### Shell & Basic (2)
+* `execute_command` [Auth Required, single command only]
+* `echo`
+
+### File Management (10)
+* `upload_file` [Auth Required]
+* `download_file`
+* `ll`
+* `cat`
+* `tail`
+* `grep`
+* `edit_text_file` [Auth Required]
+* `touch`
+* `rm_safe` [Auth Required]
+* `find`
+
+### Git (2)
+* `git_status`
+* `git_pull` [Auth Required]
+
+### Docker & Compose (17)
+* `docker_compose_up` [Auth Required]
+* `docker_compose_down` [Auth Required]
+* `docker_compose_stop` [Auth Required]
+* `docker_compose_logs`
+* `docker_compose_restart` [Auth Required]
+* `docker_ps`
+* `docker_images`
+* `docker_pull` [Auth Required]
+* `docker_cp` [Auth Required]
+* `docker_stop` [Auth Required]
+* `docker_rm` [Auth Required]
+* `docker_start` [Auth Required]
+* `docker_rmi` [Auth Required]
+* `docker_commit` [Auth Required]
+* `docker_logs`
+* `docker_load` [Auth Required]
+* `docker_save` [Auth Required]
+
+### Service & Network (7)
+* `systemctl_status`
+* `systemctl_restart` [Auth Required]
+* `systemctl_start` [Auth Required]
+* `systemctl_stop` [Auth Required]
+* `ip_addr`
+* `firewall_cmd` [Auth Required, structured actions only]
+* `netstat` [uses `args: string[]`]
+
+### Stats & Process (4)
+* `nvidia_smi`
+* `ps`
+* `df_h`
+* `du_sh`
+
+Total: 50 tools.
+
+---
+
+## 🔐 The Confirmation Workflow
+
+1.  **Request**: AI calls `execute_command({ command: 'systemctl restart nginx' })`.
+2.  **Intercept**: Server returns `status: "pending"` with a `confirmationId`.
+3.  **Human Input**: You review the action in your chat client and approve.
+4.  **Execution**: AI calls `execute_command` again with the `confirmationId` and `confirmExecution: true`.
+5.  **Verify**: Server ensures parameters match exactly and executes the SSH command.
+
+If a high-risk tool's final command string matches `commandWhitelist`, the server skips the pending confirmation step and runs it directly. For `execute_batch`, only non-whitelisted high-risk sub-commands keep the batch in the confirmation flow.
+
+`execute_command` is limited to one shell command segment. The server rejects chaining operators such as `&&`, `||`, `;`, pipes, redirection, subshell syntax, and multiline input. For built-in tools, user-provided parameters are shell-escaped before execution to reduce command injection risk.
+
+`firewall_cmd` no longer accepts a free-form shell fragment. Use structured fields such as `action`, `port`, `zone`, `permanent`, and `listTarget`. `netstat` now accepts `args: string[]` so each option is validated as an individual token.
+
+---
+
+## 📄 License
+Released under the [MIT License](./LICENSE).

package/dist/config.js

@@ -117,6 +117,9 @@ export class ConfigManager {
     getGlobalBlacklist() {
         return this.config.commandBlacklist || [];
     }
+    getGlobalWhitelist() {
+        return this.config.commandWhitelist || [];
+    }
     getDefaultTimeout() {
         return this.config.defaultTimeout || 60000;
     }

package/dist/tools/definitions.js

@@ -55,7 +55,7 @@ export const toolDefinitions = [
     // --- Batch (Core) ---
     {
         name: 'execute_batch',
-        description: 'Workflow automation: Executes a sequence of multiple tools in a single persistent SSH session. REQUIRES CONFIRMATION if any sub-tool is high-risk.',
+        description: 'Workflow automation: Executes a sequence of multiple tools in a single persistent SSH session. REQUIRES CONFIRMATION when any high-risk sub-tool final command is not whitelisted.',
         inputSchema: baseParams({
             commands: {
                 type: 'array',
@@ -75,7 +75,7 @@ export const toolDefinitions = [
     // --- Shell & Basic (Requirements) ---
     {
         name: 'execute_command',
-        description: 'Arbitrary execution: Runs any shell command via SSH. REQUIRES CONFIRMATION.',
+        description: 'Single-command execution: Runs exactly one shell command segment via SSH. Rejects chaining, pipes, redirection, subshell syntax, and multiline input. REQUIRES CONFIRMATION unless the final command is whitelisted.',
         inputSchema: baseParams({
             command: { type: 'string' },
             ...cwdParam,
@@ -115,6 +115,16 @@ export const toolDefinitions = [
         description: 'File reading: Reads text file content.',
         inputSchema: baseParams({ filePath: { type: 'string' }, ...grepParam }, ['filePath'])
     },
+    {
+        name: 'tail',
+        description: 'Log inspection: Reads last N lines of a file.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, lines: { type: 'number' }, ...grepParam }, ['filePath'])
+    },
+    {
+        name: 'grep',
+        description: 'Pattern search: Search for a regex pattern in a file.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, pattern: { type: 'string' }, ignoreCase: { type: 'boolean' } }, ['filePath', 'pattern'])
+    },
     {
         name: 'edit_text_file',
         description: 'File creation/overwrite: Completely replaces file content. REQUIRES CONFIRMATION.',
@@ -129,11 +139,27 @@ export const toolDefinitions = [
         description: 'Timestamp/File creation: Updates access time or creates empty file.',
         inputSchema: baseParams({ filePath: { type: 'string' } }, ['filePath'])
     },
+    {
+        name: 'rm_safe',
+        description: 'File deletion: Removes file or directory. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ path: { type: 'string' }, recursive: { type: 'boolean' }, ...confirmationParams }, ['path'])
+    },
     {
         name: 'find',
         description: 'Search for files in a directory hierarchy.',
         inputSchema: baseParams({ path: { type: 'string' }, name: { type: 'string' }, ...grepParam }, ['path'])
     },
+    // --- Git ---
+    {
+        name: 'git_status',
+        description: 'Git status: Displays repository status.',
+        inputSchema: baseParams(cwdParam)
+    },
+    {
+        name: 'git_pull',
+        description: 'Git update: Pulls latest changes. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ ...cwdParam, ...confirmationParams })
+    },
     // --- Docker & Compose (Requirements) ---
     {
         name: 'docker_compose_up',
@@ -248,13 +274,20 @@ export const toolDefinitions = [
     },
     {
         name: 'firewall_cmd',
-        description: 'Control the runtime/permanent firewall. REQUIRES CONFIRMATION.',
-        inputSchema: baseParams({ args: { type: 'string' }, ...confirmationParams }, ['args'])
+        description: 'Structured firewall control. Supports action=list|add-port|remove-port|reload with optional zone, permanent, and listTarget. REQUIRES CONFIRMATION unless the final command is whitelisted.',
+        inputSchema: baseParams({
+            action: { type: 'string', enum: ['list', 'add-port', 'remove-port', 'reload'] },
+            listTarget: { type: 'string', enum: ['ports', 'services', 'all'] },
+            port: { type: 'string' },
+            zone: { type: 'string' },
+            permanent: { type: 'boolean' },
+            ...confirmationParams
+        }, ['action'])
     },
     {
         name: 'netstat',
-        description: 'Monitor ports/connections.',
-        inputSchema: baseParams({ args: { type: 'string' }, ...grepParam })
+        description: 'Monitor ports/connections. Use args as an array of individual option tokens, for example ["-t", "-u", "-l", "-n"].',
+        inputSchema: baseParams({ args: { type: 'array', items: { type: 'string' } }, ...grepParam })
     },
     // --- Stats & Process (Requirements) ---
     {

package/dist/tools/handlers.js

@@ -4,6 +4,8 @@ const WRITE_TOOLS = [
     'execute_command',
     'upload_file',
     'edit_text_file',
+    'rm_safe',
+    'git_pull',
     'docker_compose_up',
     'docker_compose_down',
     'docker_compose_stop',
@@ -36,6 +38,13 @@ export class ToolHandlers {
     constructor(configManager) {
         this.configManager = configManager;
     }
+    /**
+     * Build regex list from config patterns using case-insensitive matching to keep
+     * behavior aligned with the existing blacklist implementation.
+     */
+    compileUserPatterns(patterns) {
+        return patterns.map((pattern) => new RegExp(pattern, 'i'));
+    }
     getServerConfig(alias) {
         const config = this.configManager.getServerConfig(alias);
         if (!config) {
@@ -51,29 +60,159 @@ export class ToolHandlers {
         }
         return cwd;
     }
+    /**
+     * Escape arbitrary text as a single POSIX shell argument to avoid command
+     * injection through built-in tool parameters.
+     */
+    shellEscape(value) {
+        return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+    }
+    /**
+     * execute_command is intentionally limited to one command segment. Chaining,
+     * pipes, subshells, redirection, and multiline payloads must use safer tools
+     * or execute_batch instead.
+     */
+    validateSingleCommand(command) {
+        this.ensureNoShellControl(command, 'execute_command only supports a single command without shell chaining, pipes, redirection, subshells, or multiline input.');
+    }
+    /**
+     * Validate free-form option fragments that intentionally allow spaces but must
+     * never introduce shell control syntax.
+     */
+    validateShellFragment(value, fieldName) {
+        this.ensureNoShellControl(value, `${fieldName} contains forbidden shell control characters.`);
+    }
+    /**
+     * Validate one shell token that is expected to remain a single argument.
+     */
+    validateShellToken(value, fieldName) {
+        if (/\s/.test(value)) {
+            throw new Error(`${fieldName} must be a single token without spaces.`);
+        }
+        this.validateShellFragment(value, fieldName);
+    }
+    ensureNoShellControl(value, errorMessage) {
+        const forbiddenOperators = [/&&/, /\|\|/, /;/, /\|/, /\$\(/, /`/, />/, /</, /\r|\n/];
+        for (const pattern of forbiddenOperators) {
+            if (pattern.test(value)) {
+                throw new Error(errorMessage);
+            }
+        }
+    }
     checkBlacklist(command) {
-        const userBlacklist = this.configManager.getGlobalBlacklist();
-        const combined = [...DEFAULT_BLACKLIST, ...userBlacklist.map(p => new RegExp(p, 'i'))];
-        for (const pattern of combined) {
+        const userBlacklist = this.compileUserPatterns(this.configManager.getGlobalBlacklist());
+        const normalizedCommand = this.stripQuotedLiterals(command);
+        for (const pattern of DEFAULT_BLACKLIST) {
+            if (pattern.test(normalizedCommand)) {
+                throw new Error(`Security Violation: Prohibited pattern: ${pattern.toString()}`);
+            }
+        }
+        for (const pattern of userBlacklist) {
             if (pattern.test(command)) {
                 throw new Error(`Security Violation: Prohibited pattern: ${pattern.toString()}`);
             }
         }
     }
+    /**
+     * Remove quoted literal payloads before evaluating built-in default blacklist
+     * rules so escaped user arguments do not look like executable shell syntax.
+     */
+    stripQuotedLiterals(command) {
+        return command
+            .replace(/'[^']*'/g, "''")
+            .replace(/"([^"\\]|\\.)*"/g, '""');
+    }
+    /**
+     * Whitelisted execute_command payloads can bypass the confirmation flow, but
+     * they still must pass blacklist validation first.
+     */
+    isCommandWhitelisted(command) {
+        const userWhitelist = this.compileUserPatterns(this.configManager.getGlobalWhitelist());
+        return userWhitelist.some((pattern) => pattern.test(command));
+    }
+    /**
+     * Resolve the exact shell command string that will be executed for command-based
+     * tools so that security rules operate on the same final text.
+     */
+    getExecutableCommand(name, params) {
+        let command = this.getCommandForTool(name, params);
+        if (!command)
+            return '';
+        if (params.grep) {
+            this.validateShellFragment(params.grep, 'grep');
+            command += ` | grep -E ${this.shellEscape(params.grep)}`;
+        }
+        return command;
+    }
+    /**
+     * Determine whether the current tool invocation still needs confirmation after
+     * command whitelist rules are applied to the final executable command.
+     */
+    requiresConfirmation(name, params) {
+        if (name !== 'execute_batch') {
+            if (!WRITE_TOOLS.includes(name))
+                return false;
+            const command = this.getExecutableCommand(name, params);
+            return command ? !this.isCommandWhitelisted(command) : true;
+        }
+        return params.commands?.some((cmd) => {
+            if (!WRITE_TOOLS.includes(cmd.name))
+                return false;
+            const command = this.getExecutableCommand(cmd.name, cmd.arguments);
+            return command ? !this.isCommandWhitelisted(command) : true;
+        }) ?? false;
+    }
+    /**
+     * Determine whether a tool invocation is fundamentally a write action,
+     * regardless of whether whitelist rules later skip manual confirmation.
+     */
+    isWriteToolCall(name, params) {
+        if (name !== 'execute_batch') {
+            return WRITE_TOOLS.includes(name);
+        }
+        return params.commands?.some((cmd) => WRITE_TOOLS.includes(cmd.name)) ?? false;
+    }
+    /**
+     * Apply blacklist validation to every command-bearing tool invocation before
+     * confirmation and execution.
+     */
+    validateToolCommand(name, params) {
+        if (name === 'execute_command') {
+            this.validateSingleCommand(params.command);
+        }
+        if (name === 'netstat' && Array.isArray(params.args)) {
+            for (const [index, arg] of params.args.entries()) {
+                this.validateShellToken(arg, `netstat.args[${index}]`);
+            }
+        }
+        const command = this.getExecutableCommand(name, params);
+        if (command) {
+            this.checkBlacklist(command);
+        }
+    }
     getCommandForTool(name, params) {
         switch (name) {
             case 'get_system_info': return 'echo "USER: $(whoami)"; echo "UPTIME: $(uptime)"; echo "KERNEL: $(uname -a)"; echo "MEMORY:"; free -m';
-            case 'check_dependencies': return `for cmd in ${params.commands.join(' ')}; do which $cmd || echo "$cmd not found"; done`;
+            case 'check_dependencies': return `for cmd in ${params.commands.map((cmd) => this.shellEscape(cmd)).join(' ')}; do which "$cmd" || echo "$cmd not found"; done`;
             case 'pwd': return 'pwd';
-            case 'cd': return `cd ${params.path}`;
+            case 'cd': return `cd ${this.shellEscape(params.path)}`;
             case 'll': return 'ls -l';
-            case 'cat': return `cat ${params.filePath}`;
+            case 'cat': return `cat ${this.shellEscape(params.filePath)}`;
+            case 'tail': return `tail -n ${params.lines || 50} ${this.shellEscape(params.filePath)}`;
+            case 'grep': return `grep ${params.ignoreCase ? '-inE' : '-nE'} ${this.shellEscape(params.pattern)} ${this.shellEscape(params.filePath)}`;
             case 'edit_text_file':
                 const edB64 = Buffer.from(params.content).toString('base64');
-                return `echo "${edB64}" | base64 -d > ${params.filePath}`;
-            case 'touch': return `touch ${params.filePath}`;
-            case 'echo': return `echo "${params.text}"`;
-            case 'find': return `find ${params.path} -name "${params.name}"`;
+                return `printf '%s' ${this.shellEscape(edB64)} | base64 -d > ${this.shellEscape(params.filePath)}`;
+            case 'touch': return `touch ${this.shellEscape(params.filePath)}`;
+            case 'rm_safe':
+                const restricted = ['/', '/etc', '/usr', '/bin', '/var', '/root', '/home'];
+                if (restricted.includes(params.path.trim()))
+                    throw new Error(`RM_SAFE: Denied for restricted directory.`);
+                return `rm ${params.recursive ? '-rf' : '-f'} ${this.shellEscape(params.path)}`;
+            case 'echo': return `echo ${this.shellEscape(params.text)}`;
+            case 'find': return `find ${this.shellEscape(params.path)} -name ${this.shellEscape(params.name)}`;
+            case 'git_status': return 'git status';
+            case 'git_pull': return 'git pull --no-edit';
             case 'execute_command': return params.command;
             case 'docker_compose_up': return 'docker-compose up -d';
             case 'docker_compose_down': return 'docker-compose down --remove-orphans';
@@ -82,30 +221,81 @@ export class ToolHandlers {
             case 'docker_compose_restart': return 'docker-compose restart';
             case 'docker_ps': return 'docker ps';
             case 'docker_images': return 'docker images';
-            case 'docker_pull': return `docker pull ${params.image}`;
-            case 'docker_cp': return `docker cp ${params.source} ${params.destination}`;
-            case 'docker_stop': return `docker stop ${params.container}`;
-            case 'docker_rm': return `docker rm ${params.container}`;
-            case 'docker_start': return `docker start ${params.container}`;
-            case 'docker_rmi': return `docker rmi ${params.image}`;
-            case 'docker_commit': return `docker commit ${params.container} ${params.repository}`;
-            case 'docker_logs': return `docker logs -n ${params.lines || 100} ${params.container}`;
-            case 'docker_load': return `docker load -i ${params.path}`;
-            case 'docker_save': return `docker save -o ${params.path} ${params.image}`;
-            case 'systemctl_status': return `systemctl status ${params.service}`;
-            case 'systemctl_restart': return `systemctl restart ${params.service}`;
-            case 'systemctl_start': return `systemctl start ${params.service}`;
-            case 'systemctl_stop': return `systemctl stop ${params.service}`;
+            case 'docker_pull': return `docker pull ${this.shellEscape(params.image)}`;
+            case 'docker_cp': return `docker cp ${this.shellEscape(params.source)} ${this.shellEscape(params.destination)}`;
+            case 'docker_stop': return `docker stop ${this.shellEscape(params.container)}`;
+            case 'docker_rm': return `docker rm ${this.shellEscape(params.container)}`;
+            case 'docker_start': return `docker start ${this.shellEscape(params.container)}`;
+            case 'docker_rmi': return `docker rmi ${this.shellEscape(params.image)}`;
+            case 'docker_commit': return `docker commit ${this.shellEscape(params.container)} ${this.shellEscape(params.repository)}`;
+            case 'docker_logs': return `docker logs -n ${params.lines || 100} ${this.shellEscape(params.container)}`;
+            case 'docker_load': return `docker load -i ${this.shellEscape(params.path)}`;
+            case 'docker_save': return `docker save -o ${this.shellEscape(params.path)} ${this.shellEscape(params.image)}`;
+            case 'systemctl_status': return `systemctl status ${this.shellEscape(params.service)}`;
+            case 'systemctl_restart': return `systemctl restart ${this.shellEscape(params.service)}`;
+            case 'systemctl_start': return `systemctl start ${this.shellEscape(params.service)}`;
+            case 'systemctl_stop': return `systemctl stop ${this.shellEscape(params.service)}`;
             case 'ip_addr': return 'ip addr';
-            case 'firewall_cmd': return `firewall-cmd ${params.args}`;
-            case 'netstat': return `netstat ${params.args || '-tuln'}`;
+            case 'firewall_cmd':
+                return this.buildFirewallCommand(params);
+            case 'netstat':
+                return `netstat ${(params.args && params.args.length > 0) ? params.args.map((arg, index) => {
+                    this.validateShellToken(arg, `netstat.args[${index}]`);
+                    return arg;
+                }).join(' ') : '-tuln'}`;
             case 'df_h': return 'df -h';
-            case 'du_sh': return `du -sh ${params.path}`;
+            case 'du_sh': return `du -sh ${this.shellEscape(params.path)}`;
             case 'nvidia_smi': return 'nvidia-smi';
             case 'ps': return 'ps aux';
             default: return '';
         }
     }
+    /**
+     * Build firewall-cmd from structured inputs so the service controls the final
+     * command shape instead of accepting a free-form shell fragment.
+     */
+    buildFirewallCommand(params) {
+        const parts = ['firewall-cmd'];
+        if (params.zone) {
+            this.validateShellToken(params.zone, 'firewall_cmd.zone');
+            parts.push(`--zone=${params.zone}`);
+        }
+        if (params.permanent) {
+            parts.push('--permanent');
+        }
+        switch (params.action) {
+            case 'reload':
+                parts.push('--reload');
+                break;
+            case 'list': {
+                const listTarget = params.listTarget || 'ports';
+                const targetMap = {
+                    ports: '--list-ports',
+                    services: '--list-services',
+                    all: '--list-all'
+                };
+                const targetFlag = targetMap[listTarget];
+                if (!targetFlag) {
+                    throw new Error(`Unsupported firewall_cmd.listTarget: ${listTarget}`);
+                }
+                parts.push(targetFlag);
+                break;
+            }
+            case 'add-port':
+            case 'remove-port': {
+                if (!params.port) {
+                    throw new Error(`firewall_cmd action '${params.action}' requires 'port'.`);
+                }
+                this.validateShellToken(params.port, 'firewall_cmd.port');
+                const flag = params.action === 'add-port' ? '--add-port' : '--remove-port';
+                parts.push(`${flag}=${params.port}`);
+                break;
+            }
+            default:
+                throw new Error(`Unsupported firewall_cmd action: ${params.action}`);
+        }
+        return parts.join(' ');
+    }
     async handleTool(name, args) {
         if (name === 'list_servers') {
             const servers = this.configManager.getAllServers();
@@ -127,11 +317,19 @@ export class ToolHandlers {
                 return `Connection failed for server '${serverAlias}': ${err.message}`;
             }
         }
+        this.validateToolCommand(name, params);
+        if (name === 'execute_batch') {
+            for (const cmd of params.commands || []) {
+                this.validateToolCommand(cmd.name, cmd.arguments);
+            }
+        }
         // --- Confirmation Logic ---
-        const isWriteAction = WRITE_TOOLS.includes(name) || (name === 'execute_batch' && params.commands?.some((c) => WRITE_TOOLS.includes(c.name)));
+        const isWriteToolCall = this.isWriteToolCall(name, params);
+        const isWriteAction = this.requiresConfirmation(name, params);
+        if (isWriteToolCall && srv.readOnly) {
+            throw new Error(`Server '${serverAlias}' is read-only.`);
+        }
         if (isWriteAction) {
-            if (srv.readOnly)
-                throw new Error(`Server '${serverAlias}' is read-only.`);
             if (confirmationId && confirmExecution === true) {
                 const isValid = confirmationManager.validateAndPop(confirmationId, name, serverAlias, args);
                 if (!isValid)
@@ -152,10 +350,6 @@ export class ToolHandlers {
             const commands = params.commands;
             let results = [];
             let currentBatchCwd = this.resolveCwd(srv, params.cwd);
-            for (const cmd of commands) {
-                if (cmd.name === 'execute_command')
-                    this.checkBlacklist(cmd.arguments.command);
-            }
             return await SSHClient.runSession(srv, async (conn) => {
                 for (const cmd of commands) {
                     if (cmd.name === 'cd') {
@@ -163,21 +357,17 @@ export class ToolHandlers {
                         results.push(`Directory changed to: ${currentBatchCwd}`);
                         continue;
                     }
-                    let cmdStr = this.getCommandForTool(cmd.name, cmd.arguments);
+                    let cmdStr = this.getExecutableCommand(cmd.name, cmd.arguments);
                     if (!cmdStr) {
                         results.push(`[${cmd.name}] Error: Not supported in batch.`);
                         continue;
                     }
-                    if (cmd.arguments.grep)
-                        cmdStr += ` | grep -E "${cmd.arguments.grep.replace(/"/g, '\\"')}"`;
                     const res = await SSHClient.executeOnConn(conn, cmdStr, currentBatchCwd, timeout);
                     results.push(`[${cmd.name}]\n${res.stdout}${res.stderr ? '\n[STDERR]\n' + res.stderr : ''}`);
                 }
                 return results.join('\n\n---\n\n');
             });
         }
-        if (name === 'execute_command')
-            this.checkBlacklist(params.command);
         const cwd = this.resolveCwd(srv, params.cwd);
         if (name === 'list_working_directories') {
             if (!srv.workingDirectories || Object.keys(srv.workingDirectories).length === 0) {
@@ -195,10 +385,8 @@ export class ToolHandlers {
             await SSHClient.downloadFile(srv, params.remotePath, params.localPath);
             return `Successfully downloaded ${params.remotePath} to ${params.localPath}`;
         }
-        let commandToRun = this.getCommandForTool(name, params);
+        let commandToRun = this.getExecutableCommand(name, params);
         if (commandToRun) {
-            if (params.grep)
-                commandToRun += ` | grep -E "${params.grep.replace(/"/g, '\\"')}"`;
             const res = await SSHClient.executeCommand(srv, commandToRun, cwd, timeout);
             let out = res.stdout;
             if (res.stderr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jadchene/mcp-ssh-service",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "A production-ready, highly secure SSH MCP server featuring stateless connections, two-step operation confirmation, and comprehensive DevOps tool integration.",
   "main": "dist/index.js",
   "type": "module",
@@ -10,11 +10,12 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build",
-    "watch": "tsc -w",
-    "prepublishOnly": "npm run build",
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test ./tests/handlers.test.mjs",
+    "prepare": "npm run build",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build",
     "start": "node dist/index.js"
   },
   "keywords": [