codex-plugin-doctor 1.22.0 → 1.23.0

package/README.md

@@ -370,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.22.0
+      - uses: Esquetta/CodexPluginDoctor@v1.23.0
         with:
-          version: "1.22.0"
+          version: "1.23.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/rules/rule-catalog.js

@@ -197,6 +197,24 @@ export const ruleCatalog = [
         fix: "Pin dependencies through a package manager or check in a reviewed setup script.",
         example: '{ "command": "npx", "args": ["-y", "@scope/server"] }'
     },
+    {
+        id: "plugin.security.path_traversal_risk",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server passes a package-external path to a path-like runtime argument.",
+        why: "Runtime file arguments outside the plugin root can load code or configuration that was not included in the reviewed package.",
+        fix: "Keep runtime file arguments inside the plugin package root, or package the referenced file with the plugin.",
+        example: '{ "command": "node", "args": ["server.js", "--config", "config/server.json"] }'
+    },
+    {
+        id: "plugin.security.dangerous_env_usage",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server sets an environment variable that can alter code loading.",
+        why: "Variables such as NODE_OPTIONS, NODE_PATH, PYTHONPATH, LD_PRELOAD, or DYLD_INSERT_LIBRARIES can inject imports, preload native libraries, or load modules outside the reviewed package.",
+        fix: "Remove code-loading environment overrides, or keep referenced modules and preload files inside the reviewed plugin package.",
+        example: '{ "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }'
+    },
     {
         id: "plugin.security.cwd_outside_root",
         category: "security",

package/dist/security/security-audit.js

@@ -41,6 +41,104 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
+const pathLikeArgFlags = new Set([
+    "--config",
+    "--config-path",
+    "--cwd",
+    "--dir",
+    "--directory",
+    "--file",
+    "--import",
+    "--loader",
+    "--path",
+    "--project",
+    "--require",
+    "--root",
+    "--script",
+    "--tsconfig",
+    "--workspace"
+]);
+const codeLoadingEnvKeys = new Set([
+    "LD_PRELOAD",
+    "DYLD_INSERT_LIBRARIES"
+]);
+const modulePathEnvKeys = new Set([
+    "NODE_PATH",
+    "PYTHONPATH",
+    "RUBYLIB"
+]);
+function looksLikeEnvReference(value) {
+    return /^\$\{?[A-Z0-9_]+\}?$/i.test(value.trim());
+}
+function looksLikePathValue(value) {
+    const trimmed = value.trim();
+    return (trimmed.includes("..") ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\") ||
+        trimmed.startsWith(".") ||
+        trimmed.startsWith("~") ||
+        path.isAbsolute(trimmed));
+}
+function isEscapingPathValue(rootPath, value) {
+    const trimmed = value.trim();
+    if (!trimmed ||
+        looksLikeEnvReference(trimmed) ||
+        /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ||
+        !looksLikePathValue(trimmed)) {
+        return false;
+    }
+    return !isPathWithinRoot(rootPath, path.resolve(rootPath, trimmed));
+}
+function collectEscapingPathArgs(rootPath, args) {
+    if (!Array.isArray(args)) {
+        return [];
+    }
+    const stringArgs = args.filter((arg) => typeof arg === "string");
+    const findings = [];
+    for (let index = 0; index < stringArgs.length; index += 1) {
+        const arg = stringArgs[index];
+        const equalsIndex = arg.indexOf("=");
+        if (equalsIndex > 0) {
+            const flag = arg.slice(0, equalsIndex).toLowerCase();
+            const value = arg.slice(equalsIndex + 1);
+            if (pathLikeArgFlags.has(flag) && isEscapingPathValue(rootPath, value)) {
+                findings.push({ flag, value });
+            }
+            continue;
+        }
+        const flag = arg.toLowerCase();
+        const value = stringArgs[index + 1];
+        if (pathLikeArgFlags.has(flag) && value && isEscapingPathValue(rootPath, value)) {
+            findings.push({ flag, value });
+            index += 1;
+        }
+    }
+    return findings;
+}
+function splitModulePathEnvValue(value) {
+    const trimmed = value.trim();
+    if (/^[a-z]:[\\/]/i.test(trimmed)) {
+        return trimmed.includes(";") ? trimmed.split(";") : [trimmed];
+    }
+    return trimmed.includes(";") ? trimmed.split(";") : trimmed.split(":");
+}
+function hasEscapingModulePath(rootPath, value) {
+    return splitModulePathEnvValue(value).some((entry) => isEscapingPathValue(rootPath, entry));
+}
+function isDangerousEnvUsage(rootPath, envKey, envValue) {
+    if (typeof envValue !== "string" || looksLikeEnvReference(envValue)) {
+        return false;
+    }
+    const normalizedKey = envKey.toUpperCase();
+    if (codeLoadingEnvKeys.has(normalizedKey)) {
+        return true;
+    }
+    if (normalizedKey === "NODE_OPTIONS" &&
+        /(?:^|\s)--(?:require|import|loader|experimental-loader)(?:=|\s+)/i.test(envValue)) {
+        return true;
+    }
+    return modulePathEnvKeys.has(normalizedKey) && hasEscapingModulePath(rootPath, envValue);
+}
 const poisonScanExtensions = new Set([
     ".json",
     ".md",
@@ -84,12 +182,23 @@ export function auditMcpServerConfig(rootPath, parsedConfig) {
         if (containsPipeInstaller(args)) {
             findings.push(buildFinding("fail", "plugin.security.remote_pipe_install", `The MCP server \`${serverName}\` appears to pipe remote content into a shell.`, "Download-and-execute install patterns can run unreviewed remote code during plugin startup.", "Pin dependencies through the package manager or check in a reviewed setup script instead of piping remote content to a shell."));
         }
+        for (const riskyArg of collectEscapingPathArgs(rootPath, args)) {
+            findings.push(buildFinding("fail", "plugin.security.path_traversal_risk", `The MCP server \`${serverName}\` passes \`${riskyArg.value}\` to path-like arg \`${riskyArg.flag}\`, which escapes the plugin root.`, "Path-like runtime arguments that point outside the package can make startup depend on unreviewed local files or load code outside the reviewed tarball.", "Keep runtime file arguments inside the plugin package root, or package the referenced file with the plugin."));
+        }
         if (typeof cwd === "string") {
             const cwdPath = path.resolve(rootPath, cwd);
             if (!isPathWithinRoot(rootPath, cwdPath)) {
                 findings.push(buildFinding("fail", "plugin.security.cwd_outside_root", `The MCP server \`${serverName}\` sets cwd outside the plugin root.`, "A working directory outside the package root can make server startup depend on unreviewed local files.", "Keep MCP server `cwd` inside the plugin package root or remove it."));
             }
         }
+        if (isPlainObject(serverConfig.env)) {
+            for (const [envKey, envValue] of Object.entries(serverConfig.env)) {
+                if (!isDangerousEnvUsage(rootPath, envKey, envValue)) {
+                    continue;
+                }
+                findings.push(buildFinding("fail", "plugin.security.dangerous_env_usage", `The MCP server \`${serverName}\` sets dangerous code-loading env variable \`${envKey}\`.`, "Environment variables that alter module lookup, preload native libraries, or inject runtime imports can execute code outside the reviewed package.", "Remove code-loading environment overrides, or keep referenced modules and preload files inside the reviewed plugin package."));
+            }
+        }
         if (typeof url === "string" && /^http:\/\//i.test(url)) {
             findings.push(buildFinding("warn", "plugin.security.insecure_http_url", `The MCP server \`${serverName}\` uses an insecure HTTP URL.`, "Plain HTTP transports can expose MCP traffic on non-local networks and make endpoint identity harder to verify.", "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints."));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",