magector 2.14.2 → 2.15.1

package/README.md

@@ -2,7 +2,7 @@
 
 **Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.**
 
-Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 45 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
+Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 46 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
 [![Node.js](https://img.shields.io/badge/node-22.5+-green.svg)](https://nodejs.org)
@@ -58,7 +58,7 @@ The result: your AI assistant calls one MCP tool and gets ranked, pattern-enrich
 - **Complexity analysis** -- cyclomatic complexity, function count, and hotspot detection across modules
 - **Fast** -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
 - **LLM description enrichment** -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
-- **MCP server** -- 45 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **MCP server** -- 46 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
 - **Clean architecture** -- Rust core handles all indexing/search, Node.js MCP server delegates to it
 
 ---
@@ -70,7 +70,7 @@ flowchart LR
   subgraph node ["Node.js Layer"]
     direction TB
     G["CLI<br/>init · index · search · describe"]
-    E["MCP Server<br/>45 tools · LRU cache"]
+    E["MCP Server<br/>46 tools · LRU cache"]
     F["Persistent Serve Process"]
     G --> F
     E --> F
@@ -136,6 +136,37 @@ flowchart LR
 
 ---
 
+## Security
+
+Magector operates on source code indexed from potentially-untrusted `vendor/` dependencies and is driven by an LLM that may be manipulated via prompt injection in indexed comments, docblocks, or markdown. The following hardening applies as of **v2.15.1**:
+
+### Path traversal protection
+
+All tools that accept a `path` argument (`magento_read`, `magento_grep`, `magento_ast_search`, `magento_find_dataobject_issues`) route the input through `safePath()` / `safeRelPath()` helpers in `src/mcp-server.js`. These:
+
+1. Resolve the argument against `MAGENTO_ROOT` with `path.resolve()` (normalizes `..`, symlinks are not followed during validation).
+2. Reject any resolved path that does not lie inside `MAGENTO_ROOT`.
+
+This prevents a hostile `vendor/` comment from instructing the LLM to e.g. `magento_read` `../../home/user/.ssh/id_rsa`. Both the standalone case handlers and their `magento_batch` counterparts share the same chokepoint.
+
+### Shell injection hardening in auto-update
+
+`src/update.js` fetches the `latest` field from the npm registry and re-execs itself with the new version string. Previously this was interpolated into a shell command; a tampered registry response could inject shell metacharacters. As of v2.15.1:
+
+- The re-exec passes argv as an **array** to a no-shell spawner (no intermediate shell).
+- A semver-strict `isSafeVersion()` validator rejects any version string containing metacharacters or that does not match `X.Y.Z` / `X.Y.Z-prerelease` form.
+- Fails closed: the auto-update is silently skipped rather than run a malformed version.
+
+### Unix socket permissions
+
+The serve-proxy Unix socket at `.magector/serve.sock` is created with `chmod 0600` immediately after `listen()`. On multi-user systems, another local account can no longer connect and query the vector index (which would leak indexed source snippets). The chmod is best-effort on platforms that don't support it (logged to `.magector/magector.log`).
+
+### Reporting vulnerabilities
+
+If you find a security issue, please open an issue on the GitHub repo and mark it as security-related. Do not post reproducers that leak actual source contents from private codebases.
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -371,7 +402,7 @@ npx magector index --force
 
 ## MCP Server Tools
 
-The MCP server exposes 45 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
+The MCP server exposes 46 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
 
 ### Output Format
 
@@ -482,13 +513,14 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 | `magento_find_trigger` | Find database triggers across the codebase |
 | `magento_find_table_usage` | Find all PHP code referencing a specific database table |
 
-### Null-Safety Analysis (v2.12–v2.13)
+### Null-Safety Analysis (v2.12–v2.15)
 
 | Tool | Description |
 |------|-------------|
 | `magento_ast_search` | Structural PHP code search using [semgrep](https://semgrep.dev). Understands PHP AST — matches by structure regardless of variable names, ignores comments/strings. Pattern syntax: `$X` = any expression, `$Y` = any identifier, `...` = any args. Example: `$X->getPayment()->$Y(...)`. Requires `semgrep`. **(v2.12)** |
 | `magento_enrich` | Build the method-chain enrichment index. Scans all `vendor/` PHP files for `->firstMethod()->secondMethod()` chains and detects null guards in surrounding code. Stores results in `.magector/enrichment.db` (SQLite, `node:sqlite`). Runs automatically after `magento_index`. **(v2.13)** |
 | `magento_find_null_risks` | Query the enrichment index for method chains without null guards. O(1) SQLite query instead of file scanning. Pass `firstMethod` to filter (e.g., `"getPayment"` → all `->getPayment()->anything()` without null guard). Requires `magento_enrich`. **(v2.13)** |
+| `magento_find_dataobject_issues` | Detect `setX(null)` anti-pattern on Magento `DataObject` subclasses. `setX(null)` stores `['x' => null]` in `_data` — `hasX()` (via `array_key_exists`) returns `true` even when the value is `null`, creating false-positive guard conditions. Use during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. Requires `semgrep`. **(v2.15)** |
 
 ### Search Enhancements (v2.1)
 
@@ -672,7 +704,7 @@ cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index
 magector/
 ├── src/                          # Node.js source
 │   ├── cli.js                    # CLI entry point (npx magector <command>)
-│   ├── mcp-server.js             # MCP server (45 tools, structured JSON output)
+│   ├── mcp-server.js             # MCP server (46 tools, structured JSON output)
 │   ├── binary.js                 # Platform binary resolver
 │   ├── model.js                  # ONNX model resolver/downloader
 │   ├── init.js                   # Full init command (index + IDE config)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.14.2",
+  "version": "2.15.1",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -33,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "2.14.2",
-    "@magector/cli-linux-x64": "2.14.2",
-    "@magector/cli-linux-arm64": "2.14.2",
-    "@magector/cli-win32-x64": "2.14.2"
+    "@magector/cli-darwin-arm64": "2.15.1",
+    "@magector/cli-linux-x64": "2.15.1",
+    "@magector/cli-linux-arm64": "2.15.1",
+    "@magector/cli-win32-x64": "2.15.1"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -17,7 +17,7 @@ import {
 import { execFileSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
 import { createServer as createNetServer, createConnection } from 'net';
-import { existsSync, statSync, unlinkSync, copyFileSync, renameSync, appendFileSync, writeFileSync, readFileSync, mkdirSync, openSync, closeSync, constants as fsConstants } from 'fs';
+import { existsSync, statSync, unlinkSync, copyFileSync, renameSync, appendFileSync, writeFileSync, readFileSync, mkdirSync, openSync, closeSync, chmodSync, constants as fsConstants } from 'fs';
 import { stat } from 'fs/promises';
 import { glob } from 'glob';
 import path from 'path';
@@ -149,6 +149,38 @@ const SOCK_PATH = path.join(config.magentoRoot, '.magector', 'serve.sock');
 const FORMAT_CACHE_PATH = path.join(config.magentoRoot, '.magector', 'format-ok.json');
 const PRIMARY_LOCK_PATH = path.join(config.magentoRoot, '.magector', 'primary.lock');
 
+// ─── Path Safety ────────────────────────────────────────────────
+// All tool handlers accept user-supplied paths relative to MAGENTO_ROOT.
+// Without validation, `../../../etc/passwd` would escape the project.
+// A hostile indexed file could prompt-inject the LLM into requesting such a
+// path and leak host files. These helpers are the single chokepoint.
+
+/**
+ * Resolve a user-supplied path against a trusted root and verify it stays
+ * inside the root. Returns the absolute resolved path or null on escape.
+ */
+function safePath(root, rel) {
+  if (rel === undefined || rel === null) return null;
+  const rootAbs = path.resolve(root);
+  const joined = path.resolve(rootAbs, String(rel));
+  if (joined !== rootAbs && !joined.startsWith(rootAbs + path.sep)) {
+    return null;
+  }
+  return joined;
+}
+
+/**
+ * Like safePath but returns the relative form (used for tools that invoke
+ * external processes with cwd=root and want a relative path argument).
+ * '.' means "the root itself".
+ */
+function safeRelPath(root, rel) {
+  const abs = safePath(root, rel);
+  if (!abs) return null;
+  const r = path.relative(path.resolve(root), abs);
+  return r === '' ? '.' : r;
+}
+
 /**
  * Expand brace patterns in include globs for GNU grep compatibility.
  * GNU grep --include does NOT support brace expansion (that's a shell feature).
@@ -737,7 +769,13 @@ function startSocketProxy() {
     logToFile('WARN', `Socket proxy error: ${err.message}`);
   });
   socketServer.listen(SOCK_PATH, () => {
-    logToFile('INFO', `Socket proxy listening on ${SOCK_PATH}`);
+    // Restrict socket to the owning user — without this, on multi-user
+    // systems any local account could connect to the serve proxy and query
+    // the index (leaking indexed code snippets to other local users).
+    try { chmodSync(SOCK_PATH, 0o600); } catch (err) {
+      logToFile('WARN', `Failed to chmod socket to 0600: ${err.message}`);
+    }
+    logToFile('INFO', `Socket proxy listening on ${SOCK_PATH} (mode 0600)`);
   });
 }
 
@@ -3663,7 +3701,11 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   const root = config.magentoRoot;
   if (!root) throw new Error('MAGENTO_ROOT not set');
 
-  const targetPath = searchPath ? path.join(root, searchPath) : root;
+  const targetPath = searchPath ? safePath(root, searchPath) : path.resolve(root);
+  if (!targetPath) {
+    logToFile('WARN', `ast_search: rejected path traversal attempt: "${searchPath}"`);
+    throw new Error(`Path escapes project root: ${searchPath}`);
+  }
   const semgrepLang = lang || 'php';
   const limit = Math.min(maxResults || 50, 200);
 
@@ -3728,12 +3770,34 @@ async function astSearch(pattern, searchPath, lang, maxResults) {
   if (parsed.errors && parsed.errors.length > 0) {
     logToFile('WARN', `ast_search: semgrep reported ${parsed.errors.length} error(s): ${parsed.errors.slice(0, 3).map(e => e.message || e.type || JSON.stringify(e)).join('; ')}`);
   }
-  return findings.map(r => ({
-    file: r.path.replace(root + '/', ''),
-    line: r.start.line,
-    endLine: r.end.line,
-    snippet: (r.extra?.lines || '').trim()
-  }));
+  return findings.map(r => {
+    // semgrep >=1.100 may return "requires login" in r.extra.lines for unlicensed installs.
+    // Fall back to r.extra.message which contains the matched expression (always available).
+    const rawLines = r.extra?.lines || '';
+    const snippet = (rawLines && rawLines !== 'requires login')
+      ? rawLines.trim()
+      : (r.extra?.message || '').trim();
+    return {
+      file: r.path.replace(root + '/', ''),
+      line: r.start.line,
+      endLine: r.end.line,
+      snippet
+    };
+  });
+}
+
+// ─── DataObject set-null Anti-pattern Detection ─────────────────
+
+async function findDataObjectIssues(searchPath, maxResults) {
+  // Detects DataObject::setX(null) anti-pattern:
+  //   setX(null) stores ['x' => null] in _data — key EXISTS with null value.
+  //   hasX() / hasData('x') calls array_key_exists() → returns true even for null.
+  //   This causes false-positive guard conditions: hasX() passes, getX() returns null.
+  //   Correct way to fully clear: unsetData('x') removes the key entirely.
+  const allResults = await astSearch('$X->$SETTER(null)', searchPath, 'php', 500);
+  const setterNullRegex = /->set[A-Z]\w+\s*\(\s*null\s*\)/;
+  const limit = Math.min(maxResults || 100, 500);
+  return allResults.filter(r => setterNullRegex.test(r.snippet)).slice(0, limit);
 }
 
 // ─── MCP Server ─────────────────────────────────────────────────
@@ -4494,6 +4558,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['pattern']
       }
     },
+    {
+      name: 'magento_find_dataobject_issues',
+      description: 'Detect DataObject::setX(null) anti-pattern calls. In Magento, classes extending DataObject store values in a _data array. Calling setX(null) stores the key with a null value — so hasX()/hasData(\'x\') (which use array_key_exists) return true even though the value is null. Downstream guard conditions silently pass, but getX() returns null. The correct way to clear is unsetData(\'x\'). Use this during field-lifecycle audits or when debugging "value persists but shouldn\'t" bugs. ⚡ For multi-query workflows use magento_batch.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"'
+          },
+          maxResults: {
+            type: 'number',
+            description: 'Maximum matches to return (default: 100, max: 500)',
+            default: 100
+          }
+        }
+      }
+    },
     {
       name: 'magento_enrich',
       description: 'Build the method-chain enrichment index. Scans all vendor/ PHP files for two-step method chains (->firstMethod()->secondMethod()) and analyses whether each call has a null guard in surrounding code. Results stored in .magector/enrichment.db. Run this once after magento_index, then use magento_find_null_risks for instant O(1) null-safety queries instead of 20+ grep calls. Also runs automatically after magento_index completes.',
@@ -4583,7 +4665,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // These tools have filesystem/di.xml fallbacks — work without serve process
     'magento_find_class', 'magento_find_method', 'magento_find_plugin',
     'magento_find_observer', 'magento_find_di_wiring', 'magento_module_structure',
-    'magento_batch', 'magento_find_config', 'magento_find_callers', 'magento_grep', 'magento_read', 'magento_trace_api', 'magento_ast_search', 'magento_find_null_risks'];
+    'magento_batch', 'magento_find_config', 'magento_find_callers', 'magento_grep', 'magento_read', 'magento_trace_api', 'magento_ast_search', 'magento_find_null_risks', 'magento_find_dataobject_issues'];
   if (warmupInProgress && !indexFreeTools.includes(name)) {
     logToFile('REQ', `${name} → blocked (warmup: loading index)`);
     return {
@@ -6426,7 +6508,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
               }
               case 'magento_read': {
-                const filePath = path.join(config.magentoRoot, a.path);
+                const filePath = safePath(config.magentoRoot, a.path);
+                if (!filePath) {
+                  logToFile('WARN', `batch read: rejected path traversal attempt: "${a.path}"`);
+                  text = `Path escapes project root: ${a.path}`;
+                  break;
+                }
                 let fileContent;
                 try { fileContent = readFileSync(filePath, 'utf-8'); } catch {
                   text = `File not found: ${a.path}`;
@@ -6451,7 +6538,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
               }
               case 'magento_grep': {
-                const searchPath = a.path || '.';
+                const searchPath = safeRelPath(config.magentoRoot, a.path || '.');
+                if (!searchPath) {
+                  logToFile('WARN', `batch grep: rejected path traversal attempt: "${a.path}"`);
+                  text = `Path escapes project root: ${a.path}`;
+                  break;
+                }
                 const include = a.include || '*.php';
                 const maxRes = Math.min(a.maxResults || 30, 100);
                 const batchCtx = a.context !== undefined ? a.context : 4;
@@ -6485,6 +6577,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 break;
               }
+              case 'magento_find_dataobject_issues': {
+                const doResults = await findDataObjectIssues(a.path, a.maxResults);
+                if (doResults.length === 0) {
+                  text = 'No DataObject setX(null) anti-pattern calls found.';
+                } else {
+                  text = `Found ${doResults.length} setX(null) call(s) — review for DataObject anti-pattern:\n\n`;
+                  for (const r of doResults) text += `${r.file}:${r.line}: ${r.snippet}\n`;
+                }
+                break;
+              }
               case 'magento_find_null_risks': {
                 const bRoot = config.magentoRoot;
                 const bLimit = Math.min(a.limit || 100, 500);
@@ -6519,7 +6621,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'magento_grep': {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
-        const searchPath = args.path || '.';
+        const searchPath = safeRelPath(root, args.path || '.');
+        if (!searchPath) {
+          logToFile('WARN', `grep: rejected path traversal attempt: "${args.path}"`);
+          return { content: [{ type: 'text', text: `Path escapes project root: ${args.path}` }], isError: true };
+        }
         const include = args.include || '*.php';
         const maxResults = Math.min(args.maxResults || 50, 200);
         const ctxLines = args.context !== undefined ? args.context : 4;
@@ -6706,7 +6812,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'magento_read': {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
-        const filePath = path.join(root, args.path);
+        const filePath = safePath(root, args.path);
+        if (!filePath) {
+          logToFile('WARN', `read: rejected path traversal attempt: "${args.path}"`);
+          return { content: [{ type: 'text', text: `Path escapes project root: ${args.path}` }], isError: true };
+        }
         let content;
         try { content = readFileSync(filePath, 'utf-8'); } catch (err) {
           logToFile('WARN', `read: file not found: ${args.path} (${err.code || err.message})`);
@@ -6762,6 +6872,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_find_dataobject_issues': {
+        const doResults = await findDataObjectIssues(args.path, args.maxResults);
+        if (doResults.length === 0) {
+          return { content: [{ type: 'text', text: '## magento_find_dataobject_issues\n\nNo `setX(null)` calls found.' }] };
+        }
+        let doText = `## magento_find_dataobject_issues\n`;
+        doText += `Found **${doResults.length}** \`setX(null)\` call(s)\n\n`;
+        doText += `> ⚠️ **DataObject anti-pattern**: \`setX(null)\` stores \`['x' => null]\` in \`_data\` — \`hasX()\` returns \`true\` via \`array_key_exists\` even for \`null\`. `;
+        doText += `Downstream \`hasX()\` guards silently pass while \`getX()\` returns \`null\`. `;
+        doText += `**Fix**: use \`unsetData('x')\` to remove the key entirely.\n\n`;
+        for (const r of doResults) {
+          const lineInfo = r.endLine && r.endLine !== r.line ? `${r.line}-${r.endLine}` : String(r.line);
+          doText += `**${r.file}:${lineInfo}**\n\`\`\`php\n${r.snippet}\n\`\`\`\n\n`;
+        }
+        return { content: [{ type: 'text', text: doText }] };
+      }
+
       case 'magento_enrich': {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };

package/src/update.js

@@ -8,7 +8,7 @@
  * Never blocks the CLI on failure — network errors are silently ignored.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { homedir } from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -140,14 +140,29 @@ export async function checkForUpdate(command, originalArgs) {
   }
 }
 
+/**
+ * Validate a semver string to prevent shell injection via malicious registry
+ * responses. Only digits, dots, dashes and alphanumerics allowed (semver prerelease).
+ * Example: "1.2.3", "1.2.3-beta.1", "2.0.0-rc.9" — yes. "1; rm -rf ~" — no.
+ */
+function isSafeVersion(v) {
+  return typeof v === 'string' && /^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(v);
+}
+
 /**
  * Re-exec the current command with the latest version.
  */
 function reExec(current, latest, originalArgs) {
+  // Defensive: reject anything that doesn't look like a real semver so a
+  // compromised npm registry response can't inject shell metacharacters.
+  if (!isSafeVersion(latest)) {
+    return; // silently skip — never block CLI on update check
+  }
   console.log(`\n⬆  Updating magector: v${current} → v${latest}...\n`);
   try {
-    const cmd = `npx -y magector@${latest} ${originalArgs.join(' ')}`;
-    execSync(cmd, {
+    // execFileSync with an argv array (no shell) — originalArgs are passed as
+    // individual argv entries, so spaces/metachars in them can't expand.
+    execFileSync('npx', ['-y', `magector@${latest}`, ...originalArgs], {
       stdio: 'inherit',
       env: { ...process.env, MAGECTOR_NO_UPDATE: '1' }
     });