@n0zer0d4y/vulcan-file-ops 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.6] - 2025-11-16
+
+### Fixed
+
+- README.md Configuration Examples: Corrected all `--approved-folders` examples to use separate array elements instead of comma-separated strings within quotes. This fixes setup failures for users with spaces in directory paths.
+  - Before: `"C:/Users/username/projects,C:/Users/username/documents"` (breaks with spaces)
+  - After: `"C:/Users/username/projects", "C:/Users/username/documents"` (works with spaces)
+- Added clear guidance for paths containing spaces in MCP configuration
+
+### Changed
+
+- Updated all README configuration examples to use the correct array element format for better user experience
+
+## [1.1.5] - 2025-11-15
+
+### Added
+
+- Comprehensive security audit documentation suite:
+  - `docs/SNYK_VULNERABILITY_AUDIT_2025.md` - Static analysis audit report from Snyk platform
+    - Validated 5/6 Snyk findings as false positives
+    - Fixed 1 finding (defense-in-depth path validation in rollback function)
+    - Created `.snyk` policy file to suppress false positives with justifications
+  - `docs/CVE_MANUAL_AUDIT_2025-11-04.md` - Manual CVE pattern analysis audit
+    - CVE-2025-54794/54795 pattern research and mitigation validation
+    - Identified and fixed critical `make_directory` vulnerability
+  - `docs/SHELL_COMMAND_AUDIT_2025-11-04.md` - Shell command directory bypass audit (retrospective)
+    - Documents November 2024 security fix for path validation in shell command arguments
+    - 419 lines of comprehensive test coverage
+  - `docs/SECURITY_TEST_SUMMARY.md` - Security test coverage documentation
+    - 2000+ lines of security-focused tests in `src/tests/`
+    - Explicit CVE tests for CVE-2025-54794, CVE-2025-54795, CVE-2025-53109
+- Security annotations and JSDoc comments in `src/tools/write-tools.ts` for static analysis tools
+
+### Changed
+
+- Reorganized vulnerability documentation with unique, descriptive filenames:
+  - Renamed `docs/VULNERABILITY_RESEARCH_FINDINGS.md` → `docs/CVE_MANUAL_AUDIT_2025-11-04.md`
+  - Renamed `local_docs/VULNERABILITY_RESEARCH_FINDINGS.md` → `local_docs/CVE_MANUAL_AUDIT_2025-11-03_DRAFT.md`
+  - Updated dates in audit reports to reflect actual creation/audit dates (Nov 3-4, 2025)
+- Enhanced README.md Security Audit section with comprehensive audit report references
+  - Added "Latest Security Audits" section linking to all audit reports
+  - Updated CVE Protection Status with current security posture
+  - Clarified shell command directory bypass as fixed (November 2024)
+
+### Security
+
+- Added defense-in-depth path validation to `performRollback()` function in `write-tools.ts`
+  - Re-validates paths before rollback operations
+  - Protects against edge cases where allowed directories might change during multi-file operations
+
+### Removed
+
+- Deleted duplicate `VULNERABILITY_RESEARCH_FINDINGS.md` files from both `docs/` and `local_docs/` after proper renaming
+
 ## [1.1.4] - 2025-11-13
 
 ### Changed

package/README.md

@@ -1,6 +1,7 @@
 # Vulcan File Ops MCP Server
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.n0zer0d4y/vulcan-file-ops)
 ![MCP Dev](https://badge.mcpx.dev?type=dev "MCP Dev")
 [![MCP Server](https://badge.mcpx.dev?type=server "MCP Server")](https://modelcontextprotocol.io)
 [![MCP Server with Tools](https://badge.mcpx.dev?type=server&features=tools "MCP server with tools")](https://modelcontextprotocol.io)
@@ -8,7 +9,9 @@
 [![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.
+> **Secure • User-Controlled • High-Performance File Operations Server**
+
+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 VS Code extension like 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.
 
 ## Table of Contents
 
@@ -58,7 +61,7 @@ This enhanced implementation provides:
 - **Advanced File Editing**: Pattern-based modifications with flexible matching and diff preview
 - **Flexible Reading Modes**: Full file, head/tail, or arbitrary line ranges
 - **Image Vision Support**: Attach images for AI analysis and description
-- **Directory Filtering**: Exclude unwanted folders (node_modules, dist, .git) from listings
+- **Directory Filtering**: Exclude unwanted folders (node_modules, dist, .git) from listings as list_directory tool can bloat server output if these types folders, normally gitignored, are included
 - **Selective Tool Activation**: Enable only specific tools or tool categories
 - **High Performance**: Optimized search algorithms with smart recursion detection
 - **Security Controls**: Path validation, access restrictions, and shell command approval
@@ -206,7 +209,8 @@ Pre-configure specific directories for immediate access on server start:
       "args": [
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
-        "/Users/username/projects,/Users/username/documents"
+        "/Users/username/projects",
+        "/Users/username/documents"
       ]
     }
   }
@@ -223,7 +227,8 @@ Pre-configure specific directories for immediate access on server start:
       "args": [
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
-        "C:/Users/username/projects,C:/Users/username/documents"
+        "C:/Users/username/projects",
+        "C:/Users/username/documents"
       ]
     }
   }
@@ -241,7 +246,8 @@ For users running from a cloned repository (after `npm run build`):
       "command": "vulcan-file-ops",
       "args": [
         "--approved-folders",
-        "/Users/username/projects,/Users/username/documents"
+        "/Users/username/projects",
+        "/Users/username/documents"
       ]
     }
   }
@@ -357,7 +363,8 @@ All configuration options can be combined:
       "args": [
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
-        "C:/Users/username/projects,C:/Users/username/documents",
+        "C:/Users/username/projects",
+        "C:/Users/username/documents",
         "--ignored-folders",
         "node_modules,dist,.git",
         "--approved-commands",
@@ -382,7 +389,8 @@ All configuration options can be combined:
       "args": [
         "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
-        "/Users/username/projects,/Users/username/documents",
+        "/Users/username/projects",
+        "/Users/username/documents",
         "--ignored-folders",
         "node_modules,dist,.git",
         "--approved-commands",
@@ -408,7 +416,8 @@ For users running from a cloned repository (after `npm run build`):
       "command": "vulcan-file-ops",
       "args": [
         "--approved-folders",
-        "/Users/username/projects,/Users/username/documents",
+        "/Users/username/projects",
+        "/Users/username/documents",
         "--ignored-folders",
         "node_modules,dist,.git",
         "--approved-commands",
@@ -697,7 +706,8 @@ Execute shell commands with security controls
 
 **Output:** Exit code, stdout, stderr, and execution metadata
 
-**Security:** 
+**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
@@ -853,7 +863,9 @@ This MCP server implements enterprise-grade security controls to protect against
 
 ### Security Audit
 
-This server has been audited against known vulnerabilities:
+This server has been comprehensively audited against known vulnerabilities and static analysis findings:
+
+**CVE Protection Status:**
 
 - ✅ CVE-2025-54794 (Path Restriction Bypass) - **FIXED**
 - ✅ CVE-2025-54795 (Command Injection) - **PROTECTED**
@@ -861,7 +873,34 @@ This server has been audited against known vulnerabilities:
 - ✅ 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).
+**Latest Security Audits:**
+
+- 📋 [Snyk Vulnerability Audit Report - November 2025](docs/SNYK_VULNERABILITY_AUDIT_2025.md)
+  - **Status**: 5/6 Snyk findings validated as false positives, 1 finding fixed
+  - **Risk Level**: LOW - Comprehensive path traversal protection verified
+  - **Static Analysis**: Snyk false positive rate 83% due to custom validation not recognized
+  - **Test Coverage**: 2000+ lines of security tests validate all protection measures
+- 📋 [CVE Manual Audit - November 2025](docs/CVE_MANUAL_AUDIT_2025-11-04.md)
+  - **Status**: Critical `make_directory` vulnerability identified and fixed
+  - **Focus**: CVE-2025-54794/54795 pattern analysis and mitigation strategies
+  - **Date**: November 4, 2025 (Manual CVE Research)
+- 📋 [Shell Command Directory Bypass Audit - November 2025](docs/SHELL_COMMAND_AUDIT_2025-11-04.md)
+  - **Status**: ✅ Fixed November 2024 (Retrospective documentation)
+  - **Issue**: Shell commands previously could access files outside approved directories via absolute paths
+  - **Severity**: HIGH (CVSS ~7.5) - Path traversal via command arguments
+  - **Fix Status**: ✅ FIXED - Path extraction and validation implemented
+  - **Test Coverage**: 419 lines of comprehensive tests, all passing
+- 📋 [Security Test Coverage Summary](docs/SECURITY_TEST_SUMMARY.md)
+  - **Test Suite**: 2000+ lines of security-focused tests in `src/tests/`
+  - **CVE Tests**: Explicit tests for CVE-2025-54794, CVE-2025-54795, CVE-2025-53109
+  - **Coverage**: Path traversal, symlinks (129+ cases), command injection, shell bypass
+
+**Security Architecture:**
+
+- Multi-layer path validation (canonical resolution, boundary checking, symlink protection)
+- Defense-in-depth with atomic operations and race condition prevention
+- Directory whitelisting with prefix collision protection
+- Comprehensive security annotations for static analysis tools
 
 ### Supported File Types
 

package/dist/tools/write-tools.js

@@ -9,6 +9,10 @@ const ToolInputSchema = ToolSchema.shape.inputSchema;
 /**
  * Helper function to write file content based on file extension
  * Supports HTML conversion for rich formatting in PDF and DOCX files
+ *
+ * @security Path must be pre-validated via validatePath() before calling this function
+ * @param validPath - VALIDATED path (must have passed through validatePath())
+ * @param content - File content to write
  */
 async function writeFileBasedOnExtension(validPath, content) {
     const ext = path.extname(validPath).toLowerCase();
@@ -23,12 +27,14 @@ async function writeFileBasedOnExtension(validPath, content) {
                 title: fileTitle,
                 author: "vulcan-file-ops",
             });
+            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
             await fs.writeFile(validPath, pdfBuffer);
         }
         else {
             // Fallback to simple text PDF for plain text
             const { createSimpleTextPDF } = await import("../utils/pdf-writer.js");
             const pdfBuffer = await createSimpleTextPDF(content);
+            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
             await fs.writeFile(validPath, pdfBuffer);
         }
     }
@@ -39,22 +45,35 @@ async function writeFileBasedOnExtension(validPath, content) {
                 title: fileTitle,
                 author: "vulcan-file-ops",
             });
+            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
             await fs.writeFile(validPath, docxBuffer);
         }
         else {
             // Fallback to simple text DOCX for plain text
             const { createSimpleDOCX } = await import("../utils/docx-writer.js");
             const docxBuffer = await createSimpleDOCX(content);
+            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
             await fs.writeFile(validPath, docxBuffer);
         }
     }
     else {
         // Regular text file
+        // SECURITY: validPath pre-validated by validatePath() - writeFileContent adds additional atomic write protection
         await writeFileContent(validPath, content);
     }
 }
+/**
+ * Process a single file edit request with validation
+ *
+ * @security All paths validated via validatePath() before file operations
+ * @param request - Edit request with path and edits to apply
+ * @param failOnAmbiguous - Whether to fail on ambiguous matches
+ * @returns Edit result with success status and diff
+ */
 async function processFileEditRequest(request, failOnAmbiguous = true) {
     try {
+        // SECURITY: Path validated against allowed directories, symlink targets checked,
+        // prevents CVE-2025-54794 (prefix collision), CVE-2025-53109 (symlink attacks)
         const validPath = await validatePath(request.path);
         const result = await applyFileEdits(validPath, request.edits, request.dryRun || false, request.matchingStrategy || "auto", request.failOnAmbiguous !== undefined
             ? request.failOnAmbiguous
@@ -171,7 +190,11 @@ async function performRollback(rollbackData) {
     for (const item of rollbackData.reverse()) {
         // Rollback in reverse order
         try {
-            await writeFileContent(item.path, item.originalContent);
+            // Security: Re-validate path before rollback to ensure it's still within allowed directories
+            // Defense-in-depth: Even though paths were validated during edit, re-validate during rollback
+            // to protect against edge cases where allowed directories might have changed
+            const validPath = await validatePath(item.path);
+            await writeFileContent(validPath, item.originalContent);
         }
         catch (rollbackError) {
             // Log rollback failure but don't throw - we want to attempt all rollbacks
@@ -299,6 +322,12 @@ export async function handleWriteTool(name, args) {
             if (!parsed.success) {
                 throw new Error(`Invalid arguments for write_file: ${parsed.error}`);
             }
+            // SECURITY: validatePath() enforces:
+            // 1. Canonical path resolution (path.resolve + path.normalize)
+            // 2. Allowed directory boundary checking (isPathWithinAllowedDirectories)
+            // 3. Symlink resolution and target validation (fs.realpath)
+            // 4. Parent directory validation for new files
+            // Prevents: CWE-23 (Path Traversal), CVE-2025-54794, CVE-2025-53109, CVE-2025-53110
             const validPath = await validatePath(parsed.data.path);
             await writeFileBasedOnExtension(validPath, parsed.data.content);
             return {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "mcpName": "io.github.n0zer0d4y/vulcan-file-ops",
-  "description": "MCP server that gives Claude Desktop and other AI assistants filesystem superpowers—read, write, edit, and manage files like AI coding assistants",
+  "description": "MCP server for AI assistants: read, write, edit, and manage files securely on local filesystem.",
   "license": "MIT",
   "author": "Lloyd Barcatan",
   "homepage": "https://github.com/n0zer0d4y/vulcan-file-ops",