@n0zer0d4y/vulcan-file-ops 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.3] - 2025-11-13
+
+### Security
+
+- CRITICAL: Fixed shell execution directory bypass vulnerability that allowed arbitrary command execution in unapproved directories
+  - Shell commands without explicit workdir parameter now properly validate process.cwd() against allowed directories
+  - All shell executions now require at least one approved directory to be configured
+  - Added mandatory directory validation for both explicit and default working directories
+  - Enhanced error messages with clear guidance for users
+  - This is a breaking change by design for security: users must configure approved directories or provide explicit workdir parameters
+
+### Added
+
+- 7 comprehensive security tests for shell execution directory validation
+- Root Cause Analysis document: local_docs/RCA-Shell-Execution-Directory-Bypass-Vulnerability.md
+- Security fix verification document: local_docs/SECURITY-FIX-VERIFICATION.md
+
+### Changed
+
+- Updated execute_shell tool description to explicitly document security requirements
+- Updated 10+ existing tests to comply with enhanced security model
+
+### Fixed
+
+- Shell execution no longer bypasses directory validation when workdir parameter is omitted
+- Process working directory is now validated against allowed directories in all cases
+
+## [1.1.2] - 2025-01-12
+
+### Fixed
+
+- Added defensive string-to-array parsing for `make_directory` tool to handle MCP clients that incorrectly serialize array parameters as stringified JSON
+  - Workaround for Claude Desktop serialization issue
+  - Zero impact on correctly-functioning MCP clients (Cursor IDE verified)
+  - Includes diagnostic logging to identify problematic clients
+  - Comprehensive test coverage for stringified arrays and edge cases
+
+### Added
+
+- 4 new test cases for MCP client serialization workaround
+- Diagnostic logging when stringified array parameters are detected
+- Root Cause Analysis document in `local_docs/make_directory_batch_failure_rca.md`
+
 ## [1.1.1] - 2025-11-11
 
 ### Fixed

package/README.md

@@ -6,6 +6,7 @@
 [![MCP Server with Tools](https://badge.mcpx.dev?type=server&features=tools "MCP server with tools")](https://modelcontextprotocol.io)
 [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/n0zer0d4y-vulcan-file-ops-badge.png)](https://mseep.ai/app/n0zer0d4y-vulcan-file-ops)
 
 **Transform your desktop AI assistants into powerful development partners.** Vulcan File Ops bridges the gap between conversational AI (Claude Desktop, ChatGPT Desktop, etc.) and your local filesystem, unlocking the same file manipulation capabilities found in AI-powered IDEs like Cursor and Cline. Write code, refactor projects, manage documentation, and perform complex file operations—matching the power of dedicated AI coding assistants. With enterprise-grade security controls, dynamic directory registration, and intelligent tool filtering, you maintain complete control while your AI assistant handles the heavy lifting.
 
@@ -442,6 +443,8 @@ The AI will use the `register_directory` tool to gain access, then perform opera
 
 Read file contents with flexible modes (full, head, tail, range)
 
+**Note:** This tool is limited to single-file operations only. **RECOMMENDED:** Use `read_multiple_files` instead, which supports both single and batch file operations for greater flexibility.
+
 **Input:**
 
 - `path` (string): File path
@@ -482,6 +485,8 @@ Batch read multiple files concurrently
 
 Create or replace file content
 
+**Note:** This tool is limited to single-file operations only. **RECOMMENDED:** Use `write_multiple_files` instead, which supports both single and batch file operations for greater flexibility.
+
 **Input:**
 
 - `path` (string): File path
@@ -577,6 +582,8 @@ List directory contents with multiple output formats
 
 Relocate or rename files and directories
 
+**Note:** This tool is limited to single-file operations only. **RECOMMENDED:** Use `file_operations` instead, which supports move, copy, and rename operations for both single and batch files with greater flexibility.
+
 **Input:**
 
 - `source` (string): Source path
@@ -685,12 +692,16 @@ Execute shell commands with security controls
 
 - `command` (string): Shell command to execute
 - `description` (string, optional): Command purpose
-- `workdir` (string, optional): Working directory (must be within allowed directories)
+- `workdir` (string, optional): Working directory (must be within allowed directories). If not provided, process.cwd() is used and validated
 - `timeout` (number, optional): Timeout in milliseconds (default: 30000)
 
 **Output:** Exit code, stdout, stderr, and execution metadata
 
-**Security:** All file/directory paths in command arguments are automatically extracted and validated against allowed directories. Commands referencing paths outside approved directories are blocked, preventing directory restriction bypasses.
+**Security:** 
+- At least one approved directory must be configured before executing shell commands
+- Working directory (whether explicit or default process.cwd()) is always validated against allowed directories
+- All file/directory paths in command arguments are automatically extracted and validated against allowed directories
+- Commands referencing paths outside approved directories are blocked, preventing directory restriction bypasses
 
 ### Multi-File Edit Examples
 
@@ -848,6 +859,7 @@ This server has been audited against known vulnerabilities:
 - ✅ CVE-2025-54795 (Command Injection) - **PROTECTED**
 - ✅ CVE-2025-53109 (Symlink Attacks) - **PROTECTED**
 - ✅ CVE-2025-53110 (Directory Containment Bypass) - **PROTECTED**
+- ✅ Shell Execution Directory Bypass - **FIXED** (November 2024)
 
 For detailed security analysis, see [Vulnerability Research Findings](docs/VULNERABILITY_RESEARCH_FINDINGS.md).
 

package/dist/tools/filesystem-tools.js

@@ -433,10 +433,29 @@ export async function handleFileSystemTool(name, args) {
             if (!parsed.success) {
                 throw new Error(`Invalid arguments for make_directory: ${parsed.error}`);
             }
+            // Defensive handling for MCP clients that may stringify arrays
+            // Some MCP clients (e.g., Claude Desktop) incorrectly serialize array parameters
+            // as stringified JSON instead of proper arrays. This workaround detects and fixes that.
+            let pathsInput = parsed.data.paths;
+            // If paths is a string that looks like a JSON array, try to parse it
+            if (typeof pathsInput === "string" && pathsInput.trim().startsWith("[")) {
+                try {
+                    const parsedArray = JSON.parse(pathsInput);
+                    if (Array.isArray(parsedArray)) {
+                        pathsInput = parsedArray;
+                        // Log for diagnostics - helps identify which clients have serialization issues
+                        console.error("[INFO] make_directory: Detected and corrected stringified array parameter");
+                    }
+                }
+                catch {
+                    // If parsing fails, treat as single path (existing behavior)
+                    // This handles edge cases like paths literally named "[something]"
+                }
+            }
             // Normalize to array (single path or multiple paths)
-            const pathsToCreate = Array.isArray(parsed.data.paths)
-                ? parsed.data.paths
-                : [parsed.data.paths];
+            const pathsToCreate = Array.isArray(pathsInput)
+                ? pathsInput
+                : [pathsInput];
             // Validate all paths first (atomic - fail before any creation)
             const allowedDirs = getAllowedDirectories();
             const validatedPaths = pathsToCreate.map((dirPath) => {

package/dist/tools/shell-tool.js

@@ -52,9 +52,14 @@ export function getShellTools() {
             description: `Execute shell commands on the host system with security controls. ` +
                 `Commands are executed as '${shellConfig.shell} ${shellConfig.args.join(" ")} <command>' on ${shellConfig.platform}. ` +
                 `\n\nThe tool captures stdout, stderr, exit codes, and signals. ` +
-                `Working directory can be specified (must be within allowed directories). ` +
                 `Commands exceeding the timeout will be automatically terminated. ` +
-                `\n\n⚠️  SECURITY: Command substitution and certain dangerous patterns may be restricted.` +
+                `\n\n⚠️  SECURITY REQUIREMENTS:\n` +
+                `- At least ONE approved directory must be configured before executing any shell commands\n` +
+                `- Working directory (workdir parameter or process.cwd()) MUST be within allowed directories\n` +
+                `- All file/directory paths in command arguments are validated against allowed directories\n` +
+                `- Command substitution and dangerous patterns may be restricted\n` +
+                `\n` +
+                `If no workdir is specified, the server's current working directory will be used and validated.` +
                 approvedCommandsText +
                 `\n\nIMPORTANT: Always provide a clear description of what the command does and why it's needed.`,
             inputSchema: zodToJsonSchema(ShellCommandArgsSchema),
@@ -120,17 +125,36 @@ export async function handleShellTool(name, args) {
                 : ""}` +
             `To approve, add these commands to --approved-commands or .env configuration.`);
     }
-    // Validate working directory if provided
-    let workdir = process.cwd();
-    if (validatedArgs.workdir) {
-        try {
-            workdir = await validatePath(validatedArgs.workdir);
-        }
-        catch (error) {
-            throw new Error(`Invalid working directory: ${validatedArgs.workdir}\n` +
-                `Error: ${error instanceof Error ? error.message : String(error)}\n` +
-                `Working directory must be within allowed directories.`);
-        }
+    // SECURITY FIX: Validate working directory ALWAYS (not just if provided)
+    // This prevents bypass via process.cwd() when workdir is omitted
+    const allowedDirs = getAllowedDirectories();
+    // Require at least one approved directory for shell execution
+    if (allowedDirs.length === 0) {
+        throw new Error(`Access denied: Shell execution requires at least one approved directory.\n` +
+            `No allowed directories are currently configured.\n` +
+            `\n` +
+            `To execute shell commands, you must first configure allowed directories using:\n` +
+            `  1. --approved-folders CLI argument when starting the MCP server, OR\n` +
+            `  2. register_directory tool to add directories at runtime\n` +
+            `\n` +
+            `Example: register_directory with path "C:/path/to/your/project"`);
+    }
+    // Always validate working directory against allowed directories
+    let workdir = validatedArgs.workdir || process.cwd();
+    try {
+        workdir = await validatePath(workdir);
+    }
+    catch (error) {
+        throw new Error(`Access denied: Working directory is not within allowed directories.\n` +
+            `Attempted directory: ${workdir}\n` +
+            `Error: ${error instanceof Error ? error.message : String(error)}\n` +
+            `\n` +
+            `Allowed directories:\n` +
+            allowedDirs.map(d => `  - ${d}`).join('\n') +
+            `\n\n` +
+            `To execute commands in this directory:\n` +
+            `  1. Register the directory using register_directory tool, OR\n` +
+            `  2. Specify a workdir parameter within an approved directory`);
     }
     // Extract and validate paths from command arguments
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "MCP server that gives Claude Desktop and other AI assistants filesystem superpowers—read, write, edit, and manage files like AI coding assistants",
   "license": "MIT",
   "author": "Lloyd Barcatan",