codex-plugin-doctor 1.56.0 → 1.58.0

package/dist/security/security-audit.js

@@ -1,6 +1,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "../core/discover-package.js";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { readJsonFile } from "../core/read-json-file.js";
 import { inspectRemoteMcpUrl } from "../core/remote-url-policy.js";
 import { validatePlugin } from "../core/validate-plugin.js";
@@ -58,6 +59,101 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
+function relativeSourcePath(rootPath, sourcePath) {
+    return relativePackagePath(rootPath, path.resolve(rootPath, sourcePath));
+}
+export function auditHookCommand(rootPath, sourcePath, event, field, command) {
+    const evidence = { sourcePath: relativeSourcePath(rootPath, sourcePath), event, field };
+    const findings = [];
+    if (/(?:^|\s)[/-]enc(?:odedcommand)?(?=\s|$)/i.test(command)) {
+        findings.push(buildFinding("fail", "plugin.security.encoded_command", "A plugin lifecycle hook uses an encoded shell command flag.", "Encoded command payloads hide the executed script from reviewers and increase supply-chain risk.", "Replace encoded shell payloads with a checked-in script or readable direct command.", evidence));
+    }
+    if (containsHookRemotePipeInstaller(command)) {
+        findings.push(buildFinding("fail", "plugin.security.remote_pipe_install", "A plugin lifecycle hook appears to pipe remote content into a shell.", "Download-and-execute patterns can run unreviewed remote code when a host invokes the hook.", "Pin dependencies through the package manager or use a reviewed local script instead of piping remote content to a shell.", evidence));
+    }
+    if (/^\s*(?:cmd(?:\.exe)?\s+\/c|(?:powershell|pwsh)(?:\.exe)?\s+-(?:command|c)\b)/i.test(command)) {
+        findings.push(buildFinding("warn", "plugin.security.command_shell_wrapper", "A plugin lifecycle hook starts through a shell wrapper.", "Shell wrappers expand quoting, pipes, aliases, and platform-specific behavior, which makes the execution path harder to audit.", "Prefer a concrete executable or checked-in script with explicit arguments.", evidence));
+    }
+    return findings;
+}
+function containsHookRemotePipeInstaller(command) {
+    const firstPipeIndex = command.indexOf("|");
+    if (firstPipeIndex === -1)
+        return false;
+    const leftHandSide = command.slice(0, firstPipeIndex);
+    const rightHandSide = command.slice(firstPipeIndex + 1).trim();
+    const interpreter = /^(?:\/(?:[^/\s|]+\/)*(?:sh|bash)\b|(?:sh|bash)\b|(?:powershell|pwsh)(?:\.exe)?\s+-(?:command|c)\s+-\s*(?:$|[;&|])|(?:iex|invoke-expression)\b)/i;
+    return isInvokedHookDownloader(leftHandSide) && interpreter.test(rightHandSide);
+}
+function isInvokedHookDownloader(command) {
+    const tokens = command.trim().split(/\s+/).filter(Boolean);
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index].toLowerCase();
+        if (token === "env") {
+            index += 1;
+            while (index < tokens.length) {
+                const envToken = tokens[index];
+                if (envToken === "--") {
+                    index += 1;
+                    break;
+                }
+                if (envToken === "-i" || envToken === "--ignore-environment") {
+                    index += 1;
+                    continue;
+                }
+                if (envToken === "-u" || envToken === "--unset") {
+                    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tokens[index + 1] ?? "")) {
+                        return false;
+                    }
+                    index += 2;
+                    continue;
+                }
+                if (/^--unset=[A-Za-z_][A-Za-z0-9_]*$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                if (envToken === "-C" || envToken === "--chdir") {
+                    if (!tokens[index + 1] || tokens[index + 1].startsWith("-")) {
+                        return false;
+                    }
+                    index += 2;
+                    continue;
+                }
+                if (/^--chdir=\S+$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                if (/^[A-Za-z_][A-Za-z0-9_]*=\S*$/.test(envToken)) {
+                    index += 1;
+                    continue;
+                }
+                break;
+            }
+            continue;
+        }
+        if (token === "command") {
+            index += 1;
+            if (tokens[index] === "-p" || tokens[index]?.toLowerCase() === "--default-search-path") {
+                index += 1;
+            }
+            if (tokens[index] === "--") {
+                index += 1;
+            }
+            continue;
+        }
+        break;
+    }
+    const downloader = normalizeCommandName(tokens[index] ?? "");
+    if (new Set(["curl", "wget", "iwr", "irm", "invoke-webrequest", "invoke-restmethod"]).has(downloader)) {
+        return true;
+    }
+    const shell = normalizeCommandName(tokens[index] ?? "");
+    return ((shell === "powershell" || shell === "pwsh") &&
+        /^-(?:command|c)$/i.test(tokens[index + 1] ?? "") &&
+        new Set(["curl", "wget", "iwr", "irm", "invoke-webrequest", "invoke-restmethod"])
+            .has(normalizeCommandName(tokens[index + 2] ?? "")));
+}
 const pathLikeArgFlags = new Set([
     "--config",
     "--config-path",
@@ -200,16 +296,14 @@ export function auditMcpServerConfig(rootPath, parsedConfig, options = {}) {
     const configPath = options.configPath
         ? relativePackagePath(rootPath, options.configPath)
         : ".mcp.json";
-    if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
         return [
-            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not find a valid `mcpServers` object.", "Without server entries, the audit cannot evaluate command execution or remote transport risk.", "Define MCP servers under a top-level `mcpServers` object.", { configPath })
+            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not find a valid MCP server map.", "Without server entries, the audit cannot evaluate command execution or remote transport risk.", "Use a direct server map, `mcp_servers`, or `mcpServers`.", { configPath })
         ];
     }
     const findings = [];
-    for (const [serverName, serverConfig] of Object.entries(parsedConfig.mcpServers)) {
-        if (!isPlainObject(serverConfig)) {
-            continue;
-        }
+    for (const [serverName, serverConfig] of Object.entries(normalizedConfig.servers)) {
         const command = serverConfig.command;
         const args = serverConfig.args;
         const cwd = serverConfig.cwd;
@@ -395,7 +489,10 @@ async function auditMcpCommandSurface(discoveredPackage) {
 function dedupeFindings(findings) {
     const seen = new Set();
     return findings.filter((finding) => {
-        const key = `${finding.id}\n${finding.message}`;
+        const hookLocation = finding.evidence?.sourcePath && finding.evidence.event && finding.evidence.field
+            ? `${finding.evidence.sourcePath}\n${finding.evidence.event}\n${finding.evidence.field}`
+            : "";
+        const key = `${finding.id}\n${finding.message}\n${hookLocation}`;
         if (seen.has(key)) {
             return false;
         }

package/examples/README.md

@@ -1,94 +1,94 @@
-# Examples
-
-This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
-
-## Example Packs
-
-Use the smallest example that matches what you need to prove:
-
-- `codex-doctor-starter` for static manifest and skill validation.
-- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
-- `codex-doctor-risky` for security finding output.
-- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
-
-### `codex-doctor-starter`
-
-Minimal valid Codex plugin package with one skill and no runtime MCP server.
-
-Expected result:
-
-- static validation passes
-- no runtime probing needed
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-starter
-```
-
-### `codex-doctor-runtime`
-
-Valid Codex plugin package with:
-
-- skill metadata
-- `.mcp.json`
-- mock MCP stdio server
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
-- `resources/templates/list`
-- `prompts/list`
-- `prompts/get`
-
-Expected result:
-
-- static validation passes
-- runtime validation passes
-- runtime scorecard shows all supported runtime capabilities as `pass`
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-```
-
-### `codex-doctor-risky`
-
-Intentionally flawed package for showing failure output.
-
-Expected result:
-
-- security finding for hard-coded secret
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
-
-### `codex-doctor-generic-mcp`
-
-Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
-
-Expected result:
-
-- `codex-plugin-doctor mcp` passes generic MCP static health checks
-- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
-
-Command:
-
-```bash
-codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
-```
-
-## Suggested Local Flow
-
-```bash
-npm install
-npm run build
-npm link
-codex-plugin-doctor check examples/codex-doctor-starter
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
+# Examples
+
+This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
+
+## Example Packs
+
+Use the smallest example that matches what you need to prove:
+
+- `codex-doctor-starter` for static manifest and skill validation.
+- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
+- `codex-doctor-risky` for security finding output.
+- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
+
+### `codex-doctor-starter`
+
+Minimal valid Codex plugin package with one skill and no runtime MCP server.
+
+Expected result:
+
+- static validation passes
+- no runtime probing needed
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-starter
+```
+
+### `codex-doctor-runtime`
+
+Valid Codex plugin package with:
+
+- skill metadata
+- `.mcp.json`
+- mock MCP stdio server
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+- `resources/templates/list`
+- `prompts/list`
+- `prompts/get`
+
+Expected result:
+
+- static validation passes
+- runtime validation passes
+- runtime scorecard shows all supported runtime capabilities as `pass`
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+```
+
+### `codex-doctor-risky`
+
+Intentionally flawed package for showing failure output.
+
+Expected result:
+
+- security finding for hard-coded secret
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```
+
+### `codex-doctor-generic-mcp`
+
+Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
+
+Expected result:
+
+- `codex-plugin-doctor mcp` passes generic MCP static health checks
+- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
+
+Command:
+
+```bash
+codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
+```
+
+## Suggested Local Flow
+
+```bash
+npm install
+npm run build
+npm link
+codex-plugin-doctor check examples/codex-doctor-starter
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```

package/examples/codex-doctor-generic-mcp/.mcp.json

@@ -1,10 +1,10 @@
-{
-  "mcpServers": {
-    "genericRuntime": {
-      "command": "node",
-      "args": [
-        "server.js"
-      ]
-    }
-  }
-}
+{
+  "mcpServers": {
+    "genericRuntime": {
+      "command": "node",
+      "args": [
+        "server.js"
+      ]
+    }
+  }
+}

package/examples/codex-doctor-generic-mcp/server.js

@@ -1 +1 @@
-process.stdin.resume();
+process.stdin.resume();

package/examples/codex-doctor-risky/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
-{
-  "name": "codex-doctor-risky",
-  "version": "1.0.0",
-  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
-  "mcpServers": "./.mcp.json"
-}
-
+{
+  "name": "codex-doctor-risky",
+  "version": "1.0.0",
+  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-risky/.mcp.json

@@ -1,12 +1,12 @@
-{
-  "mcpServers": {
-    "dangerServer": {
-      "command": "node",
-      "args": ["./mock-server.js"],
-      "env": {
-        "OPENAI_API_KEY": "sk-live-example-secret-value"
-      }
-    }
-  }
-}
-
+{
+  "mcpServers": {
+    "dangerServer": {
+      "command": "node",
+      "args": ["./mock-server.js"],
+      "env": {
+        "OPENAI_API_KEY": "sk-live-example-secret-value"
+      }
+    }
+  }
+}
+

package/examples/codex-doctor-risky/mock-server.js

@@ -1 +1 @@
-process.stdin.resume();
+process.stdin.resume();

package/examples/codex-doctor-runtime/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
-{
-  "name": "codex-doctor-runtime",
-  "version": "1.0.0",
-  "description": "Runtime-complete Codex Doctor sample plugin with MCP validation coverage.",
-  "skills": "./skills/",
-  "mcpServers": "./.mcp.json"
-}
-
+{
+  "name": "codex-doctor-runtime",
+  "version": "1.0.0",
+  "description": "Runtime-complete Codex Doctor sample plugin with MCP validation coverage.",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}
+

package/examples/codex-doctor-runtime/.mcp.json

@@ -1,9 +1,9 @@
-{
-  "mcpServers": {
-    "doctorRuntime": {
-      "command": "node",
-      "args": ["./mock-server.js"]
-    }
-  }
-}
-
+{
+  "mcpServers": {
+    "doctorRuntime": {
+      "command": "node",
+      "args": ["./mock-server.js"]
+    }
+  }
+}
+